@chrischall/office-outlook-mcp 0.3.5 → 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/.claude-plugin/marketplace.json +2 -2
- package/.claude-plugin/plugin.json +2 -2
- package/README.md +10 -2
- package/dist/bundle.js +938 -182
- package/dist/client.js +26 -8
- package/dist/timezone.js +32 -3
- package/dist/tools/_paging.js +9 -2
- package/dist/tools/calendar.js +177 -22
- package/dist/tools/directory.js +27 -31
- package/dist/tools/healthcheck.js +4 -3
- package/dist/tools/mail.js +16 -22
- package/dist/tools/writes.js +274 -23
- package/dist/version.js +1 -1
- package/dist/view.js +9 -1
- package/package.json +2 -2
- package/server.json +14 -2
- package/skills/outlook-fpx/references/outlook-env.sh +2 -2
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
|
|
17
|
-
*
|
|
18
|
-
* top-level import
|
|
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
|
-
*
|
|
23
|
-
*
|
|
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
|
/**
|
|
@@ -228,6 +230,22 @@ export class OutlookClient {
|
|
|
228
230
|
}
|
|
229
231
|
return this.get(target.pathname.slice(prefix.length) + target.search, opts);
|
|
230
232
|
}
|
|
233
|
+
/**
|
|
234
|
+
* POST a read-only query — `findmeetingtimes`, `getschedule` — that changes
|
|
235
|
+
* nothing in the mailbox. Kept apart from `write` so a reader can tell the
|
|
236
|
+
* two apart at the call site, and because these take `Prefer` (notably
|
|
237
|
+
* `outlook.timezone`, without which every returned slot is UTC).
|
|
238
|
+
*/
|
|
239
|
+
async post(path, body, opts = {}) {
|
|
240
|
+
this.#requireConfigured();
|
|
241
|
+
return this.#client().fetchJson('POST', path, {
|
|
242
|
+
body,
|
|
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,
|
|
247
|
+
});
|
|
248
|
+
}
|
|
231
249
|
/**
|
|
232
250
|
* The single write path. Everything mutating goes through here so auth and
|
|
233
251
|
* error shaping stay in one place.
|
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
|
-
|
|
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
|
}
|
package/dist/tools/_paging.js
CHANGED
|
@@ -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
|
-
/**
|
|
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
|
-
|
|
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
|
package/dist/tools/calendar.js
CHANGED
|
@@ -1,25 +1,46 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
-
import { minifiedResult, resolveView, viewParam } from '@chrischall/mcp-utils';
|
|
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,BodyPreview';
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
7
|
+
const EVENT_SELECT = 'Id,Subject,Start,End,Location,Organizer,IsAllDay,IsCancelled,ShowAs,OnlineMeetingUrl,OnlineMeeting,BodyPreview';
|
|
8
|
+
/**
|
|
9
|
+
* An Outlook `DateTimeTimeZone` for a caller-supplied time.
|
|
10
|
+
*
|
|
11
|
+
* A wall-clock time ("2026-10-12T09:00:00") is read in `zone`, matching
|
|
12
|
+
* outlook_create_event. One carrying `Z` or an offset already names its
|
|
13
|
+
* instant, so it is converted to UTC rather than having its offset silently
|
|
14
|
+
* ignored and re-read in the mailbox zone.
|
|
15
|
+
*/
|
|
16
|
+
function dateTimeTimeZone(value, zone) {
|
|
17
|
+
if (/(Z|[+-]\d{2}:?\d{2})$/i.test(value)) {
|
|
18
|
+
const d = new Date(value);
|
|
19
|
+
if (!Number.isNaN(d.getTime())) {
|
|
20
|
+
return { DateTime: d.toISOString().replace(/\.\d{3}Z$/, ''), TimeZone: 'UTC' };
|
|
21
|
+
}
|
|
15
22
|
}
|
|
16
|
-
return
|
|
23
|
+
return { DateTime: value, TimeZone: zone };
|
|
17
24
|
}
|
|
25
|
+
function assertWindow(start, end) {
|
|
26
|
+
const a = Date.parse(start);
|
|
27
|
+
const b = Date.parse(end);
|
|
28
|
+
if (!Number.isNaN(a) && !Number.isNaN(b) && b <= a) {
|
|
29
|
+
throw new McpToolError(`The window ends (${end}) before it starts (${start}).`, {
|
|
30
|
+
hint: '`end` must be later than `start`.',
|
|
31
|
+
});
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
/** Outlook pads times to 7 fractional digits; that is noise to a reader. */
|
|
35
|
+
function trimTime(dt) {
|
|
36
|
+
return dt?.replace(/\.0+$/, '');
|
|
37
|
+
}
|
|
38
|
+
const attendeeList = (what) => z.array(z.string().min(3)).describe(`Email addresses of ${what}`);
|
|
18
39
|
export function registerCalendarTools(server, client) {
|
|
19
40
|
server.registerTool('outlook_list_events', {
|
|
20
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.' +
|
|
21
42
|
' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
|
|
22
|
-
annotations: { readOnlyHint: true },
|
|
43
|
+
annotations: { readOnlyHint: true, openWorldHint: true },
|
|
23
44
|
inputSchema: z.object({
|
|
24
45
|
view: viewParam(VIEWS),
|
|
25
46
|
start: z
|
|
@@ -36,13 +57,16 @@ export function registerCalendarTools(server, client) {
|
|
|
36
57
|
}),
|
|
37
58
|
}, async ({ view, start, end, timeZone, limit, nextLink }) => {
|
|
38
59
|
const zone = timeZone ?? (await mailboxTimeZone(client));
|
|
39
|
-
const data = await fetchPage(client, nextLink,
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
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
|
+
});
|
|
46
70
|
const v = resolveView(view, VIEWS);
|
|
47
71
|
if (v === 'raw')
|
|
48
72
|
return mailboxUntrusted(data);
|
|
@@ -51,7 +75,7 @@ export function registerCalendarTools(server, client) {
|
|
|
51
75
|
server.registerTool('outlook_get_event', {
|
|
52
76
|
description: 'Get one calendar event in full, including attendees and their responses.' +
|
|
53
77
|
' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
|
|
54
|
-
annotations: { readOnlyHint: true },
|
|
78
|
+
annotations: { readOnlyHint: true, openWorldHint: true },
|
|
55
79
|
inputSchema: z.object({
|
|
56
80
|
view: viewParam(VIEWS),
|
|
57
81
|
id: z.string().min(1).describe('Event Id from outlook_list_events'),
|
|
@@ -67,15 +91,146 @@ export function registerCalendarTools(server, client) {
|
|
|
67
91
|
});
|
|
68
92
|
server.registerTool('outlook_list_calendars', {
|
|
69
93
|
description: 'List the calendars in the mailbox, for picking one to read or write against.',
|
|
70
|
-
annotations: { readOnlyHint: true },
|
|
94
|
+
annotations: { readOnlyHint: true, openWorldHint: true },
|
|
71
95
|
inputSchema: z.object({
|
|
72
96
|
view: viewParam(VIEWS),
|
|
73
97
|
nextLink: nextLinkParam,
|
|
74
98
|
}),
|
|
75
99
|
}, async ({ view, nextLink }) => {
|
|
76
|
-
const data = await fetchPage(client, nextLink,
|
|
100
|
+
const data = await fetchPage(client, nextLink, '/me/calendars', { query: { $select: 'Id,Name,Color,CanEdit,Owner' } });
|
|
77
101
|
if (resolveView(view, VIEWS) === 'raw')
|
|
78
102
|
return minifiedResult(data);
|
|
79
103
|
return minifiedResult(plainCollection(data));
|
|
80
104
|
});
|
|
105
|
+
server.registerTool('outlook_find_meeting_times', {
|
|
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." +
|
|
107
|
+
' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
|
|
108
|
+
annotations: { readOnlyHint: true, openWorldHint: true },
|
|
109
|
+
inputSchema: z.object({
|
|
110
|
+
view: viewParam(VIEWS),
|
|
111
|
+
attendees: attendeeList('required attendees').min(1),
|
|
112
|
+
optionalAttendees: attendeeList('optional attendees').optional(),
|
|
113
|
+
start: z.string().min(1).describe('Earliest the meeting may start, e.g. 2026-10-12T09:00:00'),
|
|
114
|
+
end: z.string().min(1).describe('Latest the meeting may end, e.g. 2026-10-16T17:00:00'),
|
|
115
|
+
durationMinutes: z.number().int().min(5).max(1440).describe('Meeting length in minutes'),
|
|
116
|
+
timeZone: z
|
|
117
|
+
.string()
|
|
118
|
+
.optional()
|
|
119
|
+
.describe('Windows time-zone name, e.g. "Eastern Standard Time". Defaults to the MAILBOX time zone.'),
|
|
120
|
+
maxCandidates: z.number().int().min(1).max(50).optional().describe('Max suggestions (default 10)'),
|
|
121
|
+
workingHoursOnly: z
|
|
122
|
+
.boolean()
|
|
123
|
+
.optional()
|
|
124
|
+
.describe("Only suggest times inside working hours (default true). false searches around the clock."),
|
|
125
|
+
minimumAttendeePercentage: z
|
|
126
|
+
.number()
|
|
127
|
+
.min(0)
|
|
128
|
+
.max(100)
|
|
129
|
+
.optional()
|
|
130
|
+
.describe('Lowest confidence (0-100) a slot needs to be suggested. Lower it to see slots where not everyone is free.'),
|
|
131
|
+
isOrganizerOptional: z
|
|
132
|
+
.boolean()
|
|
133
|
+
.optional()
|
|
134
|
+
.describe("true when the signed-in user need not attend, so their own calendar is ignored"),
|
|
135
|
+
}),
|
|
136
|
+
}, async (args) => {
|
|
137
|
+
assertWindow(args.start, args.end);
|
|
138
|
+
const zone = args.timeZone ?? (await mailboxTimeZone(client)) ?? 'UTC';
|
|
139
|
+
const body = {
|
|
140
|
+
Attendees: [
|
|
141
|
+
...args.attendees.map((Address) => ({ Type: 'Required', EmailAddress: { Address } })),
|
|
142
|
+
...(args.optionalAttendees ?? []).map((Address) => ({
|
|
143
|
+
Type: 'Optional',
|
|
144
|
+
EmailAddress: { Address },
|
|
145
|
+
})),
|
|
146
|
+
],
|
|
147
|
+
TimeConstraint: {
|
|
148
|
+
ActivityDomain: args.workingHoursOnly === false ? 'Unrestricted' : 'Work',
|
|
149
|
+
Timeslots: [
|
|
150
|
+
{ Start: dateTimeTimeZone(args.start, zone), End: dateTimeTimeZone(args.end, zone) },
|
|
151
|
+
],
|
|
152
|
+
},
|
|
153
|
+
MeetingDuration: `PT${args.durationMinutes}M`,
|
|
154
|
+
MaxCandidates: args.maxCandidates ?? 10,
|
|
155
|
+
ReturnSuggestionReasons: true,
|
|
156
|
+
...(args.minimumAttendeePercentage !== undefined
|
|
157
|
+
? { MinimumAttendeePercentage: args.minimumAttendeePercentage }
|
|
158
|
+
: {}),
|
|
159
|
+
...(args.isOrganizerOptional !== undefined
|
|
160
|
+
? { IsOrganizerOptional: args.isOrganizerOptional }
|
|
161
|
+
: {}),
|
|
162
|
+
};
|
|
163
|
+
const data = await client.post('/me/findmeetingtimes', body, { prefer: `outlook.timezone="${zone}"` });
|
|
164
|
+
if (resolveView(args.view, VIEWS) === 'raw')
|
|
165
|
+
return mailboxUntrusted(data);
|
|
166
|
+
const suggestions = (data?.MeetingTimeSuggestions ?? []).map((s) => ({
|
|
167
|
+
Start: trimTime(s.MeetingTimeSlot?.Start?.DateTime),
|
|
168
|
+
End: trimTime(s.MeetingTimeSlot?.End?.DateTime),
|
|
169
|
+
Confidence: s.Confidence,
|
|
170
|
+
Organizer: s.OrganizerAvailability,
|
|
171
|
+
Attendees: Object.fromEntries((s.AttendeeAvailability ?? []).map((a) => [
|
|
172
|
+
a.Attendee?.EmailAddress?.Address ?? a.Attendee?.EmailAddress?.Name ?? '?',
|
|
173
|
+
a.Availability,
|
|
174
|
+
])),
|
|
175
|
+
Reason: s.SuggestionReason,
|
|
176
|
+
}));
|
|
177
|
+
return mailboxUntrusted({
|
|
178
|
+
timeZone: zone,
|
|
179
|
+
count: suggestions.length,
|
|
180
|
+
suggestions,
|
|
181
|
+
// Outlook explains an empty result ("AttendeesUnavailable", ...); an
|
|
182
|
+
// empty list without it reads as "nobody is ever free".
|
|
183
|
+
...(data?.EmptySuggestionsReason
|
|
184
|
+
? { emptySuggestionsReason: data.EmptySuggestionsReason }
|
|
185
|
+
: {}),
|
|
186
|
+
});
|
|
187
|
+
});
|
|
188
|
+
server.registerTool('outlook_get_schedule', {
|
|
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)." +
|
|
190
|
+
' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
|
|
191
|
+
annotations: { readOnlyHint: true, openWorldHint: true },
|
|
192
|
+
inputSchema: z.object({
|
|
193
|
+
view: viewParam(VIEWS),
|
|
194
|
+
people: attendeeList('people (or rooms) to look up').min(1).max(100),
|
|
195
|
+
start: z.string().min(1).describe('Window start, e.g. 2026-10-12T09:00:00'),
|
|
196
|
+
end: z.string().min(1).describe('Window end, e.g. 2026-10-12T17:00:00'),
|
|
197
|
+
timeZone: z
|
|
198
|
+
.string()
|
|
199
|
+
.optional()
|
|
200
|
+
.describe('Windows time-zone name, e.g. "Eastern Standard Time". Defaults to the MAILBOX time zone.'),
|
|
201
|
+
intervalMinutes: z
|
|
202
|
+
.number()
|
|
203
|
+
.int()
|
|
204
|
+
.min(5)
|
|
205
|
+
.max(1440)
|
|
206
|
+
.optional()
|
|
207
|
+
.describe('Slot size for the raw view\'s AvailabilityView string (default 30)'),
|
|
208
|
+
}),
|
|
209
|
+
}, async ({ view, people, start, end, timeZone, intervalMinutes }) => {
|
|
210
|
+
assertWindow(start, end);
|
|
211
|
+
const zone = timeZone ?? (await mailboxTimeZone(client)) ?? 'UTC';
|
|
212
|
+
const data = await client.post('/me/calendar/getschedule', {
|
|
213
|
+
Schedules: people,
|
|
214
|
+
StartTime: dateTimeTimeZone(start, zone),
|
|
215
|
+
EndTime: dateTimeTimeZone(end, zone),
|
|
216
|
+
AvailabilityViewInterval: intervalMinutes ?? 30,
|
|
217
|
+
}, { prefer: `outlook.timezone="${zone}"` });
|
|
218
|
+
if (resolveView(view, VIEWS) === 'raw')
|
|
219
|
+
return mailboxUntrusted(data);
|
|
220
|
+
const schedules = (data?.value ?? []).map((p) =>
|
|
221
|
+
// An unresolvable address must not read as "free all day".
|
|
222
|
+
p.Error !== undefined && p.Error !== null
|
|
223
|
+
? { Who: p.ScheduleId, Error: p.Error }
|
|
224
|
+
: {
|
|
225
|
+
Who: p.ScheduleId,
|
|
226
|
+
Busy: (p.ScheduleItems ?? []).map((i) => ({
|
|
227
|
+
Start: trimTime(i.Start?.DateTime),
|
|
228
|
+
End: trimTime(i.End?.DateTime),
|
|
229
|
+
Status: i.Status,
|
|
230
|
+
...(i.Subject ? { Subject: i.Subject } : {}),
|
|
231
|
+
...(i.Location ? { Location: i.Location } : {}),
|
|
232
|
+
})),
|
|
233
|
+
});
|
|
234
|
+
return mailboxUntrusted({ timeZone: zone, schedules });
|
|
235
|
+
});
|
|
81
236
|
}
|
package/dist/tools/directory.js
CHANGED
|
@@ -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,
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
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,
|
|
60
|
-
|
|
61
|
-
|
|
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,
|
|
75
|
-
|
|
76
|
-
|
|
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`,
|
|
13
|
-
*
|
|
14
|
-
*
|
|
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({
|
package/dist/tools/mail.js
CHANGED
|
@@ -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
|
|
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,
|
|
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
|
|
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
|
}
|