@teamnetwork/m365-mcp-server 1.0.1 → 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/calendar.js

@@ -22,7 +22,7 @@ export async function listEvents(client, email, params) {
             startDateTime: params.startDate,
             endDateTime: params.endDate,
         })
-            .select('id,subject,start,end,location,organizer,attendees,isOnlineMeeting,onlineMeetingUrl')
+            .select(params.select)
             .top(params.maxResults)
             .orderby('start/dateTime')
             .get();

package/dist/graph/email.js

@@ -23,7 +23,7 @@ export async function listMessages(client, email, params) {
         const folderId = params.folderId === 'Inbox' ? 'Inbox' : params.folderId;
         let req = client
             .api(`/users/${email}/mailFolders/${folderId}/messages`)
-            .select('id,subject,from,receivedDateTime,bodyPreview,hasAttachments,isRead')
+            .select(params.select)
             .top(params.maxResults)
             .orderby('receivedDateTime desc');
         if (params.bodySearch) {
@@ -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/calendar/listEvents.js

@@ -2,19 +2,31 @@ import { ListEventsSchema } from '../schemas.js';
 import { createGraphClient } from '../../graph/clientFactory.js';
 import { listEvents } from '../../graph/calendar.js';
 import { assertMailboxConfigured } from '../../middleware/readonlyGuard.js';
-import { errorResponse } from '../../utils/errors.js';
+import { errorResponse, ToolError } from '../../utils/errors.js';
 import { logger } from '../../utils/logger.js';
+import { resolveSelect, SelectValidationError, EVENT_SELECT_FIELDS, EVENT_SELECT_DEFAULT } from '../../utils/selectFields.js';
 export function registerListEvents(server, config, auth) {
     server.tool('list_events', 'List calendar events within a date range. Recurring events are expanded into individual instances.', ListEventsSchema.shape, async (params) => {
         logger.info('list_events', { accountId: params.accountId, mailbox: params.mailbox });
         try {
             assertMailboxConfigured(config, params.accountId, params.mailbox);
+            let select;
+            try {
+                select = resolveSelect(params.select, EVENT_SELECT_FIELDS, EVENT_SELECT_DEFAULT);
+            }
+            catch (err) {
+                if (err instanceof SelectValidationError) {
+                    return errorResponse(new ToolError(err.message, 'INVALID_SELECT_FIELD'));
+                }
+                throw err;
+            }
             const token = await auth.getAccessToken(params.accountId);
             const client = createGraphClient(token);
             const result = await listEvents(client, params.mailbox, {
                 startDate: params.startDate,
                 endDate: params.endDate,
                 maxResults: params.maxResults,
+                select,
                 ...(params.calendarId !== undefined && { calendarId: params.calendarId }),
             });
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };

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/email/listMessages.js

@@ -2,8 +2,9 @@ import { ListMessagesSchema } from '../schemas.js';
 import { createGraphClient } from '../../graph/clientFactory.js';
 import { listMessages } from '../../graph/email.js';
 import { assertMailboxConfigured } from '../../middleware/readonlyGuard.js';
-import { errorResponse } from '../../utils/errors.js';
+import { errorResponse, ToolError } from '../../utils/errors.js';
 import { logger } from '../../utils/logger.js';
+import { resolveSelect, SelectValidationError, MESSAGE_SELECT_FIELDS, MESSAGE_SELECT_DEFAULT } from '../../utils/selectFields.js';
 export function registerListMessages(server, config, auth) {
     server.tool('list_messages', 'List email messages in a mailbox folder with optional filters for date range, subject, body content, and sender. Returns message metadata (not full body) to keep response size small.', ListMessagesSchema.shape, async (params) => {
         logger.info('list_messages', {
@@ -14,11 +15,22 @@ export function registerListMessages(server, config, auth) {
         });
         try {
             assertMailboxConfigured(config, params.accountId, params.mailbox);
+            let select;
+            try {
+                select = resolveSelect(params.select, MESSAGE_SELECT_FIELDS, MESSAGE_SELECT_DEFAULT);
+            }
+            catch (err) {
+                if (err instanceof SelectValidationError) {
+                    return errorResponse(new ToolError(err.message, 'INVALID_SELECT_FIELD'));
+                }
+                throw err;
+            }
             const token = await auth.getAccessToken(params.accountId);
             const client = createGraphClient(token);
             const result = await listMessages(client, params.mailbox, {
                 folderId: params.folderId,
                 maxResults: params.maxResults,
+                select,
                 ...(params.startDate !== undefined && { startDate: params.startDate }),
                 ...(params.endDate !== undefined && { endDate: params.endDate }),
                 ...(params.subject !== undefined && { subject: params.subject }),

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

@@ -19,10 +19,19 @@ export const ListMessagesSchema = AccountMailbox.extend({
     bodySearch: z.string().optional().describe('Full-text search in message body. Note: cannot be combined with $filter — date/sender filters are applied client-side when this is used.'),
     sender: z.string().email().optional().describe('Filter messages from this sender email address'),
     maxResults: z.number().int().min(1).max(100).default(25).describe('Maximum number of messages to return (1–100)'),
+    select: z.array(z.string()).optional().describe('Fields to return. Omit for defaults (subject, from, receivedDateTime, isRead, hasAttachments, bodyPreview). Valid fields: id, subject, from, toRecipients, ccRecipients, bccRecipients, receivedDateTime, sentDateTime, bodyPreview, body, hasAttachments, attachmentCount, importance, isRead, isDraft, webLink, parentFolderId, conversationId'),
 });
 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'),
@@ -50,6 +59,7 @@ export const ListEventsSchema = AccountMailbox.extend({
     startDate: z.string().datetime().describe('Start of the date range (ISO 8601). Recurring events are expanded within this window.'),
     endDate: z.string().datetime().describe('End of the date range (ISO 8601)'),
     maxResults: z.number().int().min(1).max(100).default(25),
+    select: z.array(z.string()).optional().describe('Fields to return. Omit for defaults (subject, start, end, location, isOnlineMeeting). Valid fields: id, subject, start, end, location, isOnlineMeeting, onlineMeetingUrl, organizer, attendees, body, bodyPreview, categories, isRecurring, recurrence, sensitivity, showAs, uid'),
 });
 export const GetEventSchema = AccountMailbox.extend({
     eventId: z.string().describe('The event ID'),

package/dist/utils/selectFields.js

@@ -0,0 +1,83 @@
+// Allowed $select field lists and validation for list_messages and list_events.
+// id is always forced into the select regardless of what the caller requests.
+export const MESSAGE_SELECT_FIELDS = new Set([
+    'id',
+    'subject',
+    'from',
+    'toRecipients',
+    'ccRecipients',
+    'bccRecipients',
+    'receivedDateTime',
+    'sentDateTime',
+    'bodyPreview',
+    'body',
+    'hasAttachments',
+    'attachmentCount',
+    'importance',
+    'isRead',
+    'isDraft',
+    'webLink',
+    'parentFolderId',
+    'conversationId',
+]);
+export const EVENT_SELECT_FIELDS = new Set([
+    'id',
+    'subject',
+    'start',
+    'end',
+    'location',
+    'isOnlineMeeting',
+    'onlineMeetingUrl',
+    'organizer',
+    'attendees',
+    'body',
+    'bodyPreview',
+    'categories',
+    'isRecurring',
+    'recurrence',
+    'sensitivity',
+    'showAs',
+    'uid',
+]);
+export const MESSAGE_SELECT_DEFAULT = [
+    'subject',
+    'from',
+    'receivedDateTime',
+    'isRead',
+    'hasAttachments',
+    'bodyPreview',
+];
+export const EVENT_SELECT_DEFAULT = [
+    'subject',
+    'start',
+    'end',
+    'location',
+    'isOnlineMeeting',
+];
+/**
+ * Validate, normalise, and force-include `id` in a select list.
+ * Returns the final comma-separated string for Graph API $select,
+ * or throws with a descriptive message listing valid fields.
+ */
+export function resolveSelect(rawSelect, allowed, defaults) {
+    // Empty array → treat as omitted, use defaults
+    const fields = rawSelect && rawSelect.length > 0
+        ? rawSelect.map((f) => f.trim()).filter(Boolean)
+        : defaults;
+    // Validate each field
+    for (const field of fields) {
+        if (!allowed.has(field)) {
+            throw new SelectValidationError(field, allowed);
+        }
+    }
+    // id must always be present
+    const withId = fields.includes('id') ? fields : ['id', ...fields];
+    return withId.join(',');
+}
+export class SelectValidationError extends Error {
+    constructor(invalidField, allowed) {
+        const validList = [...allowed].sort().join(', ');
+        super(`Invalid select field: "${invalidField}". Valid fields: ${validList}`);
+        this.name = 'SelectValidationError';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamnetwork/m365-mcp-server",
-  "version": "1.0.1",
+  "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",