@teamnetwork/m365-mcp-server 1.0.2 → 1.0.3

package/README.md

@@ -119,10 +119,12 @@ If installed globally, you can use the `m365-mcp` command instead:
 | `list_mailboxes` | List configured accounts and mailboxes with read/write status |
 | `list_folders` | List mail folders (top-level or child folders) |
 | `list_messages` | List messages with optional filters: date range, subject, body keyword, sender |
-| `get_message` | Get full message details including body |
+| `get_message` | Get full message details including body. Set `includeAttachments: true` to expand attachment metadata inline |
 | `send_message` | Send an email (non-readonly mailboxes only) |
 | `reply_message` | Reply or reply-all to a message (non-readonly mailboxes only) |
 | `move_message` | Move a message to another folder (non-readonly mailboxes only) |
+| `list_message_attachments` | List all attachments on a message (file, item, and reference types) |
+| `download_attachment` | Download a file attachment as base64. Images returned as MCP image content; reference attachments return their preview URL |
 
 ### Calendar
 

package/dist/graph/attachments.js

@@ -0,0 +1,71 @@
+import { mapGraphError } from '../utils/errors.js';
+// ── Helpers ────────────────────────────────────────────────────────────────
+function deriveAttachmentType(odataType) {
+    if (odataType?.includes('referenceAttachment'))
+        return 'referenceAttachment';
+    if (odataType?.includes('itemAttachment'))
+        return 'itemAttachment';
+    return 'fileAttachment';
+}
+function normaliseAttachment(raw) {
+    const odataType = raw['@odata.type'];
+    const attachmentType = deriveAttachmentType(odataType);
+    const meta = {
+        id: raw['id'],
+        name: raw['name'],
+        contentType: raw['contentType'] ?? 'application/octet-stream',
+        size: raw['size'] ?? 0,
+        isInline: raw['isInline'] ?? false,
+        attachmentType,
+    };
+    if (attachmentType === 'referenceAttachment' && raw['previewUrl']) {
+        meta.previewUrl = raw['previewUrl'];
+    }
+    return meta;
+}
+// ── API calls ──────────────────────────────────────────────────────────────
+export async function listAttachments(client, email, messageId) {
+    try {
+        const response = await client
+            .api(`/users/${email}/messages/${messageId}/attachments`)
+            .select('id,name,contentType,size,isInline,previewUrl')
+            .get();
+        return (response.value ?? []).map(normaliseAttachment);
+    }
+    catch (err) {
+        throw mapGraphError(err, 'list_message_attachments');
+    }
+}
+export async function downloadAttachment(client, email, messageId, attachmentId) {
+    try {
+        // Fetch the full attachment record including contentBytes for file attachments.
+        // contentBytes is already base64-encoded by the Graph API.
+        const raw = await client
+            .api(`/users/${email}/messages/${messageId}/attachments/${attachmentId}`)
+            .select('id,name,contentType,isInline,contentBytes,previewUrl,@odata.type')
+            .get();
+        const attachmentType = deriveAttachmentType(raw['@odata.type']);
+        if (attachmentType === 'referenceAttachment') {
+            return {
+                kind: 'reference',
+                previewUrl: raw['previewUrl'] ?? raw['name'],
+            };
+        }
+        if (attachmentType === 'itemAttachment') {
+            return {
+                kind: 'item',
+                name: raw['name'],
+            };
+        }
+        // fileAttachment — contentBytes is already base64 from Graph
+        return {
+            kind: 'file',
+            name: raw['name'],
+            mimeType: raw['contentType'] ?? 'application/octet-stream',
+            contentBytes: raw['contentBytes'],
+        };
+    }
+    catch (err) {
+        throw mapGraphError(err, 'download_attachment');
+    }
+}

package/dist/graph/email.js

@@ -69,15 +69,22 @@ export async function listMessages(client, email, params) {
         throw mapGraphError(err, 'list_messages');
     }
 }
-export async function getMessage(client, email, messageId, includeBody) {
+export async function getMessage(client, email, messageId, includeBody, includeAttachments) {
     try {
-        const select = includeBody
-            ? 'id,subject,from,toRecipients,ccRecipients,body,receivedDateTime,hasAttachments,isRead'
-            : 'id,subject,from,toRecipients,ccRecipients,receivedDateTime,hasAttachments,isRead';
-        return await client
+        const selectFields = [
+            'id', 'subject', 'from', 'toRecipients', 'ccRecipients',
+            'receivedDateTime', 'hasAttachments', 'isRead',
+        ];
+        if (includeBody)
+            selectFields.push('body');
+        let req = client
             .api(`/users/${email}/messages/${messageId}`)
-            .select(select)
-            .get();
+            .select(selectFields.join(','));
+        if (includeAttachments) {
+            // Expand attachments inline — avoids a second round-trip for the caller
+            req = req.expand('attachments($select=id,name,contentType,size,isInline)');
+        }
+        return await req.get();
     }
     catch (err) {
         throw mapGraphError(err, 'get_message');

package/dist/tools/email/downloadAttachment.js

@@ -0,0 +1,69 @@
+import { DownloadAttachmentSchema } from '../schemas.js';
+import { createGraphClient } from '../../graph/clientFactory.js';
+import { downloadAttachment } from '../../graph/attachments.js';
+import { assertMailboxConfigured } from '../../middleware/readonlyGuard.js';
+import { errorResponse } from '../../utils/errors.js';
+import { logger } from '../../utils/logger.js';
+export function registerDownloadAttachment(server, config, auth) {
+    server.tool('download_attachment', 'Download a file attachment from an email message. Returns base64-encoded file content for file attachments, the preview URL for reference attachments (e.g. SharePoint links), or a descriptive message for embedded item attachments.', DownloadAttachmentSchema.shape, async (params) => {
+        logger.info('download_attachment', {
+            accountId: params.accountId,
+            mailbox: params.mailbox,
+        });
+        try {
+            assertMailboxConfigured(config, params.accountId, params.mailbox);
+            const token = await auth.getAccessToken(params.accountId);
+            const client = createGraphClient(token);
+            const result = await downloadAttachment(client, params.mailbox, params.messageId, params.attachmentId);
+            switch (result.kind) {
+                case 'file':
+                    // Images are returned as MCP image content; all other files as structured text
+                    // containing the base64 payload, mimeType, and fileName for the caller to handle.
+                    if (result.mimeType.startsWith('image/')) {
+                        return {
+                            content: [
+                                {
+                                    type: 'image',
+                                    data: result.contentBytes,
+                                    mimeType: result.mimeType,
+                                },
+                            ],
+                        };
+                    }
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    fileName: result.name,
+                                    mimeType: result.mimeType,
+                                    encoding: 'base64',
+                                    data: result.contentBytes,
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                case 'reference':
+                    return {
+                        content: [{ type: 'text', text: result.previewUrl }],
+                    };
+                case 'item':
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `itemAttachment: "${result.name}" — embedded Outlook item, not downloadable as a file`,
+                            },
+                        ],
+                    };
+            }
+        }
+        catch (err) {
+            logger.error('download_attachment failed', {
+                accountId: params.accountId,
+                mailbox: params.mailbox,
+            });
+            return errorResponse(err);
+        }
+    });
+}

package/dist/tools/email/getMessage.js

@@ -5,13 +5,13 @@ import { assertMailboxConfigured } from '../../middleware/readonlyGuard.js';
 import { errorResponse } from '../../utils/errors.js';
 import { logger } from '../../utils/logger.js';
 export function registerGetMessage(server, config, auth) {
-    server.tool('get_message', 'Get the full details of a specific email message by ID, including body content.', GetMessageSchema.shape, async (params) => {
+    server.tool('get_message', 'Get the full details of a specific email message by ID. Set includeBody to receive the message body, includeAttachments to expand attachment metadata inline.', GetMessageSchema.shape, async (params) => {
         logger.info('get_message', { accountId: params.accountId, mailbox: params.mailbox });
         try {
             assertMailboxConfigured(config, params.accountId, params.mailbox);
             const token = await auth.getAccessToken(params.accountId);
             const client = createGraphClient(token);
-            const result = await getMessage(client, params.mailbox, params.messageId, params.includeBody);
+            const result = await getMessage(client, params.mailbox, params.messageId, params.includeBody, params.includeAttachments);
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
         catch (err) {

package/dist/tools/email/listMessageAttachments.js

@@ -0,0 +1,30 @@
+import { ListMessageAttachmentsSchema } from '../schemas.js';
+import { createGraphClient } from '../../graph/clientFactory.js';
+import { listAttachments } from '../../graph/attachments.js';
+import { assertMailboxConfigured } from '../../middleware/readonlyGuard.js';
+import { errorResponse } from '../../utils/errors.js';
+import { logger } from '../../utils/logger.js';
+export function registerListMessageAttachments(server, config, auth) {
+    server.tool('list_message_attachments', 'List all attachments on a specific email message. Returns metadata for file, item, and reference attachments. Use download_attachment to retrieve file content.', ListMessageAttachmentsSchema.shape, async (params) => {
+        logger.info('list_message_attachments', {
+            accountId: params.accountId,
+            mailbox: params.mailbox,
+        });
+        try {
+            assertMailboxConfigured(config, params.accountId, params.mailbox);
+            const token = await auth.getAccessToken(params.accountId);
+            const client = createGraphClient(token);
+            const attachments = await listAttachments(client, params.mailbox, params.messageId);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ value: attachments }, null, 2) }],
+            };
+        }
+        catch (err) {
+            logger.error('list_message_attachments failed', {
+                accountId: params.accountId,
+                mailbox: params.mailbox,
+            });
+            return errorResponse(err);
+        }
+    });
+}

package/dist/tools/registry.js

@@ -6,6 +6,8 @@ import { registerGetMessage } from './email/getMessage.js';
 import { registerSendMessage } from './email/sendMessage.js';
 import { registerReplyMessage } from './email/replyMessage.js';
 import { registerMoveMessage } from './email/moveMessage.js';
+import { registerListMessageAttachments } from './email/listMessageAttachments.js';
+import { registerDownloadAttachment } from './email/downloadAttachment.js';
 // Calendar tools
 import { registerListCalendars } from './calendar/listCalendars.js';
 import { registerListEvents } from './calendar/listEvents.js';
@@ -20,6 +22,8 @@ function registerEmailTools(server, config, auth) {
     registerSendMessage(server, config, auth);
     registerReplyMessage(server, config, auth);
     registerMoveMessage(server, config, auth);
+    registerListMessageAttachments(server, config, auth);
+    registerDownloadAttachment(server, config, auth);
 }
 function registerCalendarTools(server, config, auth) {
     registerListCalendars(server, config, auth);

package/dist/tools/schemas.js

@@ -24,6 +24,14 @@ export const ListMessagesSchema = AccountMailbox.extend({
 export const GetMessageSchema = AccountMailbox.extend({
     messageId: z.string().describe('The message ID'),
     includeBody: z.boolean().default(true).describe('Whether to include the full message body in the response'),
+    includeAttachments: z.boolean().default(false).describe('Whether to expand and include attachment metadata in the response'),
+});
+export const ListMessageAttachmentsSchema = AccountMailbox.extend({
+    messageId: z.string().describe('The message ID to list attachments for'),
+});
+export const DownloadAttachmentSchema = AccountMailbox.extend({
+    messageId: z.string().describe('The message ID'),
+    attachmentId: z.string().describe('The attachment ID to download'),
 });
 export const SendMessageSchema = AccountMailbox.extend({
     to: z.array(z.string().email()).min(1).describe('List of recipient email addresses'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamnetwork/m365-mcp-server",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "MCP server for Microsoft 365 Email and Calendar access using client credentials (app-only auth). Supports multiple accounts, shared mailboxes, per-mailbox read-only access, folder navigation, and date/content filtering.",
   "type": "module",
   "main": "./dist/index.js",