@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/.claude-plugin/marketplace.json +2 -2
- package/.claude-plugin/plugin.json +2 -2
- package/dist/bundle.js +621 -174
- package/dist/client.js +13 -8
- package/dist/timezone.js +32 -3
- package/dist/tools/_paging.js +9 -2
- package/dist/tools/calendar.js +17 -24
- 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 +55 -12
- package/dist/version.js +1 -1
- package/dist/view.js +4 -0
- 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
|
/**
|
|
@@ -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
|
-
|
|
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,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,
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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,
|
|
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),
|
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
|
}
|
package/dist/tools/writes.js
CHANGED
|
@@ -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:
|
|
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:
|
|
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
|
-
|
|
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
|
|
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:
|
|
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
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.
|
|
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": "^
|
|
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",
|