@teamnetwork-nz/m365-mcp-server 1.7.1 → 1.7.2
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/README.md +1 -1
- package/config.example.json +3 -0
- package/dist/config/schema.js +4 -0
- package/dist/tools/email/downloadAttachment.js +14 -1
- package/dist/tools/schemas.js +1 -0
- package/dist/utils/attachmentFile.js +104 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -192,7 +192,7 @@ Operations always target exactly one mailbox per request, either the default or
|
|
|
192
192
|
| `reply_message` | Reply or reply-all to a message (non-readonly mailboxes only) |
|
|
193
193
|
| `move_message` | Move a message to another folder (non-readonly mailboxes only) |
|
|
194
194
|
| `list_message_attachments` | List all attachments on a message (file, item, and reference types) |
|
|
195
|
-
| `download_attachment` | Download
|
|
195
|
+
| `download_attachment` | Download an attachment. Pass `savePath` to write decoded bytes directly beneath a configured `attachmentDownloads.allowedRoots` directory and receive its path, byte count, and SHA-256. Otherwise returns base64 inline; images use MCP image content |
|
|
196
196
|
|
|
197
197
|
### Calendar
|
|
198
198
|
|
package/config.example.json
CHANGED
package/dist/config/schema.js
CHANGED
|
@@ -52,10 +52,14 @@ export const TeamsConfigSchema = z.object({
|
|
|
52
52
|
channelMessagesAllowed: z.boolean().default(false),
|
|
53
53
|
chatMessagesAllowed: z.boolean().default(false),
|
|
54
54
|
});
|
|
55
|
+
export const AttachmentDownloadsConfigSchema = z.object({
|
|
56
|
+
allowedRoots: z.array(z.string().min(1)).min(1),
|
|
57
|
+
});
|
|
55
58
|
// ── Root config ─────────────────────────────────────────────────────────────
|
|
56
59
|
export const AppConfigSchema = z.object({
|
|
57
60
|
connection: ConnectionConfigSchema,
|
|
58
61
|
accounts: z.array(AccountConfigSchema).min(1, 'Config must have at least one account'),
|
|
62
|
+
attachmentDownloads: AttachmentDownloadsConfigSchema.optional(),
|
|
59
63
|
sharepoint: z.array(SharepointLibraryConfigSchema).optional(),
|
|
60
64
|
teams: TeamsConfigSchema.optional(),
|
|
61
65
|
});
|
|
@@ -5,8 +5,9 @@ import { assertMailboxConfigured } from '../../middleware/readonlyGuard.js';
|
|
|
5
5
|
import { errorResponse } from '../../utils/errors.js';
|
|
6
6
|
import { logger } from '../../utils/logger.js';
|
|
7
7
|
import { resolveMailbox } from '../../utils/resolveMailbox.js';
|
|
8
|
+
import { writeAttachmentFile } from '../../utils/attachmentFile.js';
|
|
8
9
|
export function registerDownloadAttachment(server, config, auth) {
|
|
9
|
-
server.tool('download_attachment', 'Download one attachment using its messageId and attachmentId from list_message_attachments.
|
|
10
|
+
server.tool('download_attachment', 'Download one attachment using its messageId and attachmentId from list_message_attachments. Pass savePath to write file bytes directly beneath a server-configured attachmentDownloads.allowedRoots directory and receive a small integrity summary. Without savePath, file attachments return base64 content (images use MCP image content). Reference attachments return their preview URL; embedded Outlook items return a description. Omit accountId/mailbox to use the default configured mailbox.', DownloadAttachmentSchema.shape, async (params) => {
|
|
10
11
|
try {
|
|
11
12
|
const resolved = resolveMailbox(config, params.accountId, params.mailbox);
|
|
12
13
|
logger.info('download_attachment', { accountId: resolved.accountId, mailbox: resolved.mailbox });
|
|
@@ -16,6 +17,18 @@ export function registerDownloadAttachment(server, config, auth) {
|
|
|
16
17
|
const result = await downloadAttachment(client, resolved.mailbox, params.messageId, params.attachmentId);
|
|
17
18
|
switch (result.kind) {
|
|
18
19
|
case 'file':
|
|
20
|
+
if (params.savePath) {
|
|
21
|
+
const written = await writeAttachmentFile(result.contentBytes, params.savePath, config.attachmentDownloads?.allowedRoots);
|
|
22
|
+
const response = {
|
|
23
|
+
fileName: result.name,
|
|
24
|
+
mimeType: result.mimeType,
|
|
25
|
+
...written,
|
|
26
|
+
};
|
|
27
|
+
return {
|
|
28
|
+
content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
|
|
29
|
+
structuredContent: response,
|
|
30
|
+
};
|
|
31
|
+
}
|
|
19
32
|
if (result.mimeType.startsWith('image/')) {
|
|
20
33
|
return {
|
|
21
34
|
content: [{ type: 'image', data: result.contentBytes, mimeType: result.mimeType }],
|
package/dist/tools/schemas.js
CHANGED
|
@@ -46,6 +46,7 @@ export const ListMessageAttachmentsSchema = AccountMailbox.extend({
|
|
|
46
46
|
export const DownloadAttachmentSchema = AccountMailbox.extend({
|
|
47
47
|
messageId: z.string().describe('The message ID'),
|
|
48
48
|
attachmentId: z.string().describe('The attachment ID to download'),
|
|
49
|
+
savePath: z.string().optional().describe('Absolute local path to write the decoded attachment. The path must be beneath an attachmentDownloads.allowedRoots directory configured on the server. Existing files are never overwritten. Omit to return content inline.'),
|
|
49
50
|
});
|
|
50
51
|
export const SendMessageSchema = AccountMailbox.extend({
|
|
51
52
|
to: z.array(z.string().email()).min(1).describe('List of recipient email addresses'),
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
import { createHash, randomUUID } from 'node:crypto';
|
|
2
|
+
import { constants } from 'node:fs';
|
|
3
|
+
import { copyFile, link, lstat, unlink, writeFile } from 'node:fs/promises';
|
|
4
|
+
import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
|
|
5
|
+
import { ToolError } from './errors.js';
|
|
6
|
+
function isWithin(root, candidate) {
|
|
7
|
+
const rel = relative(root, candidate);
|
|
8
|
+
return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
|
|
9
|
+
}
|
|
10
|
+
function decodeBase64(value) {
|
|
11
|
+
const compact = value.replace(/\s/g, '');
|
|
12
|
+
if (!/^[A-Za-z0-9+/]*={0,2}$/.test(compact) || compact.length % 4 === 1) {
|
|
13
|
+
throw new ToolError('Graph returned invalid base64 attachment content.', 'INVALID_ATTACHMENT_CONTENT');
|
|
14
|
+
}
|
|
15
|
+
const unpadded = compact.replace(/=+$/, '');
|
|
16
|
+
const padded = unpadded.padEnd(Math.ceil(unpadded.length / 4) * 4, '=');
|
|
17
|
+
const bytes = Buffer.from(padded, 'base64');
|
|
18
|
+
if (bytes.toString('base64').replace(/=+$/, '') !== unpadded) {
|
|
19
|
+
throw new ToolError('Graph returned invalid base64 attachment content.', 'INVALID_ATTACHMENT_CONTENT');
|
|
20
|
+
}
|
|
21
|
+
return bytes;
|
|
22
|
+
}
|
|
23
|
+
async function assertExistingPathHasNoLinks(root, parent) {
|
|
24
|
+
const rel = relative(root, parent);
|
|
25
|
+
const paths = [root];
|
|
26
|
+
let current = root;
|
|
27
|
+
for (const segment of rel.split(sep).filter(Boolean)) {
|
|
28
|
+
current = resolve(current, segment);
|
|
29
|
+
paths.push(current);
|
|
30
|
+
}
|
|
31
|
+
for (const path of paths) {
|
|
32
|
+
let stat;
|
|
33
|
+
try {
|
|
34
|
+
stat = await lstat(path);
|
|
35
|
+
}
|
|
36
|
+
catch (err) {
|
|
37
|
+
if (err.code === 'ENOENT') {
|
|
38
|
+
throw new ToolError(`The savePath directory does not exist: "${path}".`, 'INVALID_SAVE_PATH');
|
|
39
|
+
}
|
|
40
|
+
throw new ToolError(`Could not inspect savePath directory "${path}": ${err.message}`, 'INVALID_SAVE_PATH');
|
|
41
|
+
}
|
|
42
|
+
if (!stat.isDirectory() || stat.isSymbolicLink()) {
|
|
43
|
+
throw new ToolError(`Attachment download paths must use existing directories without symbolic links: "${path}".`, 'INVALID_SAVE_PATH');
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
export async function writeAttachmentFile(contentBytes, savePath, allowedRoots) {
|
|
48
|
+
if (!allowedRoots?.length) {
|
|
49
|
+
throw new ToolError('Saving attachments is disabled. Configure attachmentDownloads.allowedRoots on the server.', 'ATTACHMENT_DOWNLOAD_DISABLED');
|
|
50
|
+
}
|
|
51
|
+
if (!isAbsolute(savePath)) {
|
|
52
|
+
throw new ToolError('savePath must be an absolute path.', 'INVALID_SAVE_PATH');
|
|
53
|
+
}
|
|
54
|
+
const destination = resolve(savePath);
|
|
55
|
+
const destinationParent = dirname(destination);
|
|
56
|
+
let allowed = false;
|
|
57
|
+
for (const configuredRoot of allowedRoots) {
|
|
58
|
+
if (!isAbsolute(configuredRoot)) {
|
|
59
|
+
throw new ToolError(`Configured attachment download root must be absolute: "${configuredRoot}".`, 'INVALID_DOWNLOAD_CONFIG');
|
|
60
|
+
}
|
|
61
|
+
const resolvedRoot = resolve(configuredRoot);
|
|
62
|
+
if (isWithin(resolvedRoot, destination)) {
|
|
63
|
+
await assertExistingPathHasNoLinks(resolvedRoot, destinationParent);
|
|
64
|
+
allowed = true;
|
|
65
|
+
break;
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
if (!allowed) {
|
|
69
|
+
throw new ToolError('savePath is outside the configured attachmentDownloads.allowedRoots.', 'SAVE_PATH_NOT_ALLOWED');
|
|
70
|
+
}
|
|
71
|
+
const bytes = decodeBase64(contentBytes);
|
|
72
|
+
const tempPath = `${destination}.${randomUUID()}.tmp`;
|
|
73
|
+
try {
|
|
74
|
+
await writeFile(tempPath, bytes, { flag: 'wx', mode: 0o600 });
|
|
75
|
+
// A hard link publishes the completed file atomically and fails if the
|
|
76
|
+
// destination already exists. This avoids platform-specific rename overwrite behavior.
|
|
77
|
+
try {
|
|
78
|
+
await link(tempPath, destination);
|
|
79
|
+
}
|
|
80
|
+
catch (err) {
|
|
81
|
+
// Some sandboxed Windows filesystems prohibit hard links. COPYFILE_EXCL
|
|
82
|
+
// preserves the critical no-overwrite guarantee in that environment.
|
|
83
|
+
if (err.code !== 'EPERM')
|
|
84
|
+
throw err;
|
|
85
|
+
await copyFile(tempPath, destination, constants.COPYFILE_EXCL);
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
catch (err) {
|
|
89
|
+
if (err.code === 'EEXIST') {
|
|
90
|
+
throw new ToolError(`Refusing to overwrite existing file: "${destination}".`, 'FILE_EXISTS');
|
|
91
|
+
}
|
|
92
|
+
if (err instanceof ToolError)
|
|
93
|
+
throw err;
|
|
94
|
+
throw new ToolError(`Could not write attachment to "${destination}": ${err.message}`, 'ATTACHMENT_WRITE_FAILED');
|
|
95
|
+
}
|
|
96
|
+
finally {
|
|
97
|
+
await unlink(tempPath).catch(() => undefined);
|
|
98
|
+
}
|
|
99
|
+
return {
|
|
100
|
+
writtenTo: destination,
|
|
101
|
+
bytes: bytes.byteLength,
|
|
102
|
+
sha256: createHash('sha256').update(bytes).digest('hex'),
|
|
103
|
+
};
|
|
104
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@teamnetwork-nz/m365-mcp-server",
|
|
3
|
-
"version": "1.7.
|
|
3
|
+
"version": "1.7.2",
|
|
4
4
|
"description": "MCP server for Microsoft 365 — Email, Calendar, To Do, SharePoint document libraries, and Teams — using client credentials (app-only auth). Supports multiple accounts, shared mailboxes, per-mailbox read-only access, and grant-based SharePoint access control.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|