@chrischall/office-outlook-mcp 0.4.0 → 0.5.0

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
@@ -6,21 +6,21 @@
6
6
  * held, every request is a plain Node `fetch` — the bridge is never on the hot
7
7
  * path.
8
8
  */
9
- import { createApiClient, decodeJwtExp, McpToolError, parseBoolEnv, readEnvVar, } from '@chrischall/mcp-utils';
9
+ import { createApiClient, decodeJwtExp, errorKindOf, errorStatusOf, McpToolError, parseBoolEnv, readEnvVar, } from '@chrischall/mcp-utils';
10
10
  import { TokenManager } from '@chrischall/mcp-utils/session';
11
11
  import { createTokenCache, reportCacheWriteFailure } from './token-cache.js';
12
12
  /**
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');
@@ -64,6 +64,16 @@ function toBearerTokens(accessToken) {
64
64
  }
65
65
  return { accessToken, refreshToken: RECAPTURE_SENTINEL, expiresAt };
66
66
  }
67
+ /**
68
+ * Whether `e` is about the credential rather than the request: no token
69
+ * configured, or Outlook refusing the one it was sent. Such a failure is the
70
+ * same for every call that follows, so a batch tool stops on it instead of
71
+ * reporting it once per item.
72
+ */
73
+ export function isCredentialFailure(e) {
74
+ const kind = errorKindOf(e);
75
+ return kind === 'no_credential' || kind === 'credential_rejected' || errorStatusOf(e) === 401;
76
+ }
67
77
  export class OutlookClient {
68
78
  #baseUrl;
69
79
  /**
@@ -95,6 +105,7 @@ export class OutlookClient {
95
105
  this.#configError = new McpToolError('No Outlook credential is configured.', {
96
106
  hint: 'Set OUTLOOK_ACCESS_TOKEN, or unset OUTLOOK_DISABLE_FETCHPROXY so the ' +
97
107
  'token can be captured from a signed-in Outlook browser tab.',
108
+ kind: 'no_credential',
98
109
  });
99
110
  }
100
111
  this.#tokenSource = direct !== undefined ? 'OUTLOOK_ACCESS_TOKEN' : 'browser capture';
@@ -129,6 +140,8 @@ export class OutlookClient {
129
140
  hint: 'A directly-supplied token cannot be refreshed automatically. Replace ' +
130
141
  'OUTLOOK_ACCESS_TOKEN with a current one, or unset it to capture from a ' +
131
142
  'signed-in Outlook browser tab instead.',
143
+ status: 401,
144
+ kind: 'credential_rejected',
132
145
  });
133
146
  }
134
147
  return toBearerTokens(await this.#capture());
@@ -175,6 +188,8 @@ export class OutlookClient {
175
188
  onUnauthorized: () => new McpToolError('Outlook rejected the access token (401).', {
176
189
  hint: 'The token has expired or been revoked. Open a signed-in Outlook tab ' +
177
190
  'and retry — the next call re-captures automatically.',
191
+ status: 401,
192
+ kind: 'credential_rejected',
178
193
  }),
179
194
  });
180
195
  return this.#api;
@@ -186,7 +201,8 @@ export class OutlookClient {
186
201
  * — measured 9.4x smaller on a real message, and it also normalises a mixed
187
202
  * HTML/Text collection to one type. `prefer` sets the `Prefer` header
188
203
  * directly, for anything else the API takes there (notably
189
- * `outlook.timezone="…"`).
204
+ * `outlook.timezone="…"`). `query` is serialised by mcp-utils'
205
+ * `buildQueryString`, which drops `undefined`/empty values.
190
206
  */
191
207
  async get(path, opts = {}) {
192
208
  this.#requireConfigured();
@@ -196,6 +212,7 @@ export class OutlookClient {
196
212
  ].filter((p) => p !== undefined);
197
213
  return this.#client().fetchJson('GET', path, {
198
214
  headers: prefer.length ? { Prefer: prefer.join(', ') } : undefined,
215
+ ...(opts.query ? { query: opts.query } : {}),
199
216
  });
200
217
  }
201
218
  /**
@@ -239,6 +256,9 @@ export class OutlookClient {
239
256
  return this.#client().fetchJson('POST', path, {
240
257
  body,
241
258
  headers: opts.prefer ? { Prefer: opts.prefer } : undefined,
259
+ // Read-only: a timeout or dropped connection is safe to retry, so keep
260
+ // the plain error rather than mcp-utils' WriteOutcomeUnknownError.
261
+ idempotent: true,
242
262
  });
243
263
  }
244
264
  /**
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
  }
@@ -0,0 +1,24 @@
1
+ /**
2
+ * The calendar item an invite message refers to, shared by the triage read
3
+ * (outlook_get_unread) and the response write (outlook_respond_to_invite) so
4
+ * the two cannot drift.
5
+ */
6
+ /** The invite's calendar item, inlined on the message it arrived as. */
7
+ export const EVENT_EXPAND = 'Microsoft.OutlookServices.EventMessage/Event';
8
+ /**
9
+ * The invite's event, or undefined when there is none to act on. Outlook
10
+ * expands an invite whose calendar item is gone (declined, cancelled or
11
+ * deleted) as an EMPTY object — live 2026-10-10: 4 of 30 meeting messages,
12
+ * all still MeetingRequest — so an Event without an Id counts as missing.
13
+ */
14
+ export function resolvedEvent(e) {
15
+ return e?.Id ? e : undefined;
16
+ }
17
+ /** Why an invite whose event did not resolve cannot be answered. */
18
+ export const INVITE_GONE = 'the meeting is no longer on your calendar (already declined, cancelled, or deleted), so there is nothing to respond to';
19
+ /** Selected beside the expand to tell a meeting message from plain mail. */
20
+ export const MEETING_MESSAGE_TYPE = 'Microsoft.OutlookServices.EventMessage/MeetingMessageType';
21
+ /** True for an EventMessage (an invite, cancellation or response), by its type or `@odata.type`. */
22
+ export function isMeetingMessage(m) {
23
+ return !!m?.MeetingMessageType || (m?.['@odata.type'] ?? '').includes('EventMessage');
24
+ }
@@ -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,12 @@
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
- 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
- }
7
+ const EVENT_SELECT = 'Id,Subject,Start,End,Location,Organizer,IsAllDay,IsCancelled,ShowAs,OnlineMeetingUrl,OnlineMeeting,BodyPreview,' +
8
+ // The decision fields (see compactEvent): your response, organizer or not, series or one-off.
9
+ 'IsOrganizer,ResponseStatus,ResponseRequested,Type,SeriesMasterId';
18
10
  /**
19
11
  * An Outlook `DateTimeTimeZone` for a caller-supplied time.
20
12
  *
@@ -50,7 +42,7 @@ export function registerCalendarTools(server, client) {
50
42
  server.registerTool('outlook_list_events', {
51
43
  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
44
  ' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
53
- annotations: { readOnlyHint: true },
45
+ annotations: { readOnlyHint: true, openWorldHint: true },
54
46
  inputSchema: z.object({
55
47
  view: viewParam(VIEWS),
56
48
  start: z
@@ -67,13 +59,16 @@ export function registerCalendarTools(server, client) {
67
59
  }),
68
60
  }, async ({ view, start, end, timeZone, limit, nextLink }) => {
69
61
  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}"` } : {});
62
+ const data = await fetchPage(client, nextLink, '/me/calendarview', {
63
+ query: {
64
+ startDateTime: start,
65
+ endDateTime: end,
66
+ $select: EVENT_SELECT,
67
+ $orderby: 'Start/DateTime',
68
+ $top: limit ?? 50,
69
+ },
70
+ ...(zone ? { prefer: `outlook.timezone="${zone}"` } : {}),
71
+ });
77
72
  const v = resolveView(view, VIEWS);
78
73
  if (v === 'raw')
79
74
  return mailboxUntrusted(data);
@@ -82,7 +77,7 @@ export function registerCalendarTools(server, client) {
82
77
  server.registerTool('outlook_get_event', {
83
78
  description: 'Get one calendar event in full, including attendees and their responses.' +
84
79
  ' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
85
- annotations: { readOnlyHint: true },
80
+ annotations: { readOnlyHint: true, openWorldHint: true },
86
81
  inputSchema: z.object({
87
82
  view: viewParam(VIEWS),
88
83
  id: z.string().min(1).describe('Event Id from outlook_list_events'),
@@ -98,25 +93,29 @@ export function registerCalendarTools(server, client) {
98
93
  });
99
94
  server.registerTool('outlook_list_calendars', {
100
95
  description: 'List the calendars in the mailbox, for picking one to read or write against.',
101
- annotations: { readOnlyHint: true },
96
+ annotations: { readOnlyHint: true, openWorldHint: true },
102
97
  inputSchema: z.object({
103
98
  view: viewParam(VIEWS),
104
99
  nextLink: nextLinkParam,
105
100
  }),
106
101
  }, async ({ view, nextLink }) => {
107
- const data = await fetchPage(client, nextLink, `/me/calendars${qs({ $select: 'Id,Name,Color,CanEdit,Owner' })}`);
102
+ const data = await fetchPage(client, nextLink, '/me/calendars', { query: { $select: 'Id,Name,Color,CanEdit,Owner' } });
108
103
  if (resolveView(view, VIEWS) === 'raw')
109
104
  return minifiedResult(data);
110
105
  return minifiedResult(plainCollection(data));
111
106
  });
112
107
  server.registerTool('outlook_find_meeting_times', {
113
- 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." +
108
+ 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 — each suggestion carries `createEventArgs` (times, zone and attendees; `subject` too when given here) to pass to it as-is. `start`/`end` are local wall-clock times in `timeZone` (default: the mailbox zone), and returned slots are in that zone too. view: 'raw' returns Outlook's response as-is, without `createEventArgs`." +
114
109
  ' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
115
- annotations: { readOnlyHint: true },
110
+ annotations: { readOnlyHint: true, openWorldHint: true },
116
111
  inputSchema: z.object({
117
112
  view: viewParam(VIEWS),
118
113
  attendees: attendeeList('required attendees').min(1),
119
114
  optionalAttendees: attendeeList('optional attendees').optional(),
115
+ subject: z
116
+ .string()
117
+ .optional()
118
+ .describe("Meeting title, carried into each suggestion's createEventArgs; not sent to Outlook"),
120
119
  start: z.string().min(1).describe('Earliest the meeting may start, e.g. 2026-10-12T09:00:00'),
121
120
  end: z.string().min(1).describe('Latest the meeting may end, e.g. 2026-10-16T17:00:00'),
122
121
  durationMinutes: z.number().int().min(5).max(1440).describe('Meeting length in minutes'),
@@ -170,17 +169,39 @@ export function registerCalendarTools(server, client) {
170
169
  const data = await client.post('/me/findmeetingtimes', body, { prefer: `outlook.timezone="${zone}"` });
171
170
  if (resolveView(args.view, VIEWS) === 'raw')
172
171
  return mailboxUntrusted(data);
173
- const suggestions = (data?.MeetingTimeSuggestions ?? []).map((s) => ({
174
- Start: trimTime(s.MeetingTimeSlot?.Start?.DateTime),
175
- End: trimTime(s.MeetingTimeSlot?.End?.DateTime),
176
- Confidence: s.Confidence,
177
- Organizer: s.OrganizerAvailability,
178
- Attendees: Object.fromEntries((s.AttendeeAvailability ?? []).map((a) => [
179
- a.Attendee?.EmailAddress?.Address ?? a.Attendee?.EmailAddress?.Name ?? '?',
180
- a.Availability,
181
- ])),
182
- Reason: s.SuggestionReason,
183
- }));
172
+ const suggestions = (data?.MeetingTimeSuggestions ?? []).map((s) => {
173
+ const start = trimTime(s.MeetingTimeSlot?.Start?.DateTime);
174
+ const end = trimTime(s.MeetingTimeSlot?.End?.DateTime);
175
+ return {
176
+ Start: start,
177
+ End: end,
178
+ Confidence: s.Confidence,
179
+ Organizer: s.OrganizerAvailability,
180
+ Attendees: Object.fromEntries((s.AttendeeAvailability ?? []).map((a) => [
181
+ a.Attendee?.EmailAddress?.Address ?? a.Attendee?.EmailAddress?.Name ?? '?',
182
+ a.Availability,
183
+ ])),
184
+ Reason: s.SuggestionReason,
185
+ // outlook_create_event's input for this slot, so booking it is a
186
+ // straight hand-off. The slot came back in `zone` (the Prefer header),
187
+ // which is also the zone create reads wall-clock times in. A slot
188
+ // without times cannot be booked, so it gets no args.
189
+ ...(start && end
190
+ ? {
191
+ createEventArgs: {
192
+ ...(args.subject !== undefined ? { subject: args.subject } : {}),
193
+ start,
194
+ end,
195
+ timeZone: zone,
196
+ attendees: args.attendees,
197
+ ...(args.optionalAttendees?.length
198
+ ? { optionalAttendees: args.optionalAttendees }
199
+ : {}),
200
+ },
201
+ }
202
+ : {}),
203
+ };
204
+ });
184
205
  return mailboxUntrusted({
185
206
  timeZone: zone,
186
207
  count: suggestions.length,
@@ -195,7 +216,7 @@ export function registerCalendarTools(server, client) {
195
216
  server.registerTool('outlook_get_schedule', {
196
217
  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
218
  ' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
198
- annotations: { readOnlyHint: true },
219
+ annotations: { readOnlyHint: true, openWorldHint: true },
199
220
  inputSchema: z.object({
200
221
  view: viewParam(VIEWS),
201
222
  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,58 @@ 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
  });
76
+ server.registerTool('outlook_list_categories', {
77
+ description: "List the mailbox's categories (the master list) with their colours — the names outlook_update_message can add or remove.",
78
+ annotations: { readOnlyHint: true, openWorldHint: true },
79
+ inputSchema: z.object({}),
80
+ }, async () => {
81
+ const data = await client.get('/me/outlook/masterCategories');
82
+ const categories = (data?.value ?? []).map((c) => ({ name: c.DisplayName, color: c.Color }));
83
+ return minifiedResult({ count: categories.length, categories });
84
+ });
80
85
  }
@@ -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({