@teamnetwork/m365-mcp-server 1.0.0

package/config.example.json

@@ -0,0 +1,27 @@
+{
+  "connection": {
+    "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "clientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "clientSecret": "your-default-client-secret"
+  },
+  "accounts": [
+    {
+      "id": "main",
+      "displayName": "Main Organisation",
+      "mailboxes": [
+        { "email": "user@org.com", "readonly": false, "displayName": "Primary User" },
+        { "email": "shared@org.com", "readonly": true, "displayName": "Shared Mailbox (read-only)" }
+      ]
+    },
+    {
+      "id": "partner",
+      "displayName": "Partner Tenant",
+      "tenantId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
+      "clientId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
+      "clientSecret": "partner-specific-secret",
+      "mailboxes": [
+        { "email": "partner@other.com", "readonly": false }
+      ]
+    }
+  ]
+}

package/dist/auth/AuthManager.js

@@ -0,0 +1,19 @@
+import { ToolError } from '../utils/errors.js';
+const GRAPH_SCOPE = 'https://graph.microsoft.com/.default';
+export class AuthManager {
+    cache;
+    constructor(cache) {
+        this.cache = cache;
+    }
+    async getAccessToken(accountId) {
+        const client = this.cache.getClient(accountId);
+        const result = await client.acquireTokenByClientCredential({
+            scopes: [GRAPH_SCOPE],
+        });
+        if (!result?.accessToken) {
+            throw new ToolError(`Failed to acquire access token for account "${accountId}" — check tenant ID, client ID, and client secret`, 'AUTH_FAILED');
+        }
+        // Token value is intentionally not logged — see utils/logger.ts scrubbing rules
+        return result.accessToken;
+    }
+}

package/dist/auth/TokenCache.js

@@ -0,0 +1,25 @@
+import { ConfidentialClientApplication } from '@azure/msal-node';
+import { resolveCredentials } from '../config/loader.js';
+export class TokenCache {
+    clients = new Map();
+    constructor(config) {
+        for (const account of config.accounts) {
+            const creds = resolveCredentials(config, account);
+            this.clients.set(account.id, new ConfidentialClientApplication({
+                auth: {
+                    clientId: creds.clientId,
+                    clientSecret: creds.clientSecret,
+                    authority: `https://login.microsoftonline.com/${creds.tenantId}`,
+                },
+                // No cache plugin = default in-memory cache only (no disk persistence)
+            }));
+        }
+    }
+    getClient(accountId) {
+        const client = this.clients.get(accountId);
+        if (!client) {
+            throw new Error(`Unknown account ID: "${accountId}". Check your config file.`);
+        }
+        return client;
+    }
+}

package/dist/config/loader.js

@@ -0,0 +1,31 @@
+import { readFileSync } from 'fs';
+import { AppConfigSchema } from './schema.js';
+export function loadConfig() {
+    const configPath = process.env['M365_CONFIG_PATH'];
+    if (!configPath) {
+        throw new Error('M365_CONFIG_PATH environment variable is not set');
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+    }
+    catch (err) {
+        throw new Error(`Failed to read config file at "${configPath}": ${err.message}`);
+    }
+    const result = AppConfigSchema.safeParse(raw);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  - ${i.path.join('.')}: ${i.message}`)
+            .join('\n');
+        throw new Error(`Config validation failed:\n${issues}`);
+    }
+    return Object.freeze(result.data);
+}
+/** Merge connection defaults with per-account overrides. Account fields win. */
+export function resolveCredentials(config, account) {
+    return {
+        tenantId: account.tenantId ?? config.connection.tenantId,
+        clientId: account.clientId ?? config.connection.clientId,
+        clientSecret: account.clientSecret ?? config.connection.clientSecret,
+    };
+}

package/dist/config/schema.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export const ConnectionConfigSchema = z.object({
+    tenantId: z.string().uuid('connection.tenantId must be a valid UUID'),
+    clientId: z.string().uuid('connection.clientId must be a valid UUID'),
+    clientSecret: z.string().min(1, 'connection.clientSecret must not be empty'),
+});
+export const MailboxConfigSchema = z.object({
+    email: z.string().email('mailbox.email must be a valid email address'),
+    readonly: z.boolean(),
+    displayName: z.string().optional(),
+});
+export const AccountConfigSchema = z.object({
+    id: z.string().min(1, 'account.id must not be empty'),
+    displayName: z.string().optional(),
+    tenantId: z.string().uuid().optional(),
+    clientId: z.string().uuid().optional(),
+    clientSecret: z.string().min(1).optional(),
+    mailboxes: z.array(MailboxConfigSchema).min(1, 'Each account must have at least one mailbox'),
+});
+export const AppConfigSchema = z.object({
+    connection: ConnectionConfigSchema,
+    accounts: z.array(AccountConfigSchema).min(1, 'Config must have at least one account'),
+});

package/dist/config/types.js

@@ -0,0 +1 @@
+export {};

package/dist/graph/calendar.js

@@ -0,0 +1,109 @@
+import { mapGraphError } from '../utils/errors.js';
+export async function listCalendars(client, email) {
+    try {
+        return await client
+            .api(`/users/${email}/calendars`)
+            .select('id,name,canEdit,color,isDefaultCalendar')
+            .get();
+    }
+    catch (err) {
+        throw mapGraphError(err, 'list_calendars');
+    }
+}
+export async function listEvents(client, email, params) {
+    try {
+        // calendarView expands recurring events into individual instances within the window
+        const basePath = params.calendarId
+            ? `/users/${email}/calendars/${params.calendarId}/calendarView`
+            : `/users/${email}/calendarView`;
+        return await client
+            .api(basePath)
+            .query({
+            startDateTime: params.startDate,
+            endDateTime: params.endDate,
+        })
+            .select('id,subject,start,end,location,organizer,attendees,isOnlineMeeting,onlineMeetingUrl')
+            .top(params.maxResults)
+            .orderby('start/dateTime')
+            .get();
+    }
+    catch (err) {
+        throw mapGraphError(err, 'list_events');
+    }
+}
+export async function getEvent(client, email, eventId) {
+    try {
+        return await client
+            .api(`/users/${email}/events/${eventId}`)
+            .select('id,subject,body,start,end,location,organizer,attendees,isOnlineMeeting,onlineMeeting,recurrence')
+            .get();
+    }
+    catch (err) {
+        throw mapGraphError(err, 'get_event');
+    }
+}
+export async function createEvent(client, email, params) {
+    try {
+        const basePath = params.calendarId
+            ? `/users/${email}/calendars/${params.calendarId}/events`
+            : `/users/${email}/events`;
+        const attendees = (params.attendees ?? []).map((addr) => ({
+            emailAddress: { address: addr },
+            type: 'required',
+        }));
+        const body = {
+            subject: params.subject,
+            start: { dateTime: params.startTime, timeZone: params.timeZone },
+            end: { dateTime: params.endTime, timeZone: params.timeZone },
+            isOnlineMeeting: params.isOnlineMeeting,
+        };
+        if (params.body !== undefined) {
+            body['body'] = {
+                contentType: params.bodyType === 'html' ? 'HTML' : 'Text',
+                content: params.body,
+            };
+        }
+        if (params.location) {
+            body['location'] = { displayName: params.location };
+        }
+        if (attendees.length > 0) {
+            body['attendees'] = attendees;
+        }
+        return await client.api(basePath).post(body);
+    }
+    catch (err) {
+        throw mapGraphError(err, 'create_event');
+    }
+}
+export async function updateEvent(client, email, eventId, params) {
+    try {
+        const patch = {};
+        if (params.subject !== undefined)
+            patch['subject'] = params.subject;
+        if (params.body !== undefined) {
+            patch['body'] = {
+                contentType: (params.bodyType ?? 'text') === 'html' ? 'HTML' : 'Text',
+                content: params.body,
+            };
+        }
+        if (params.startTime !== undefined) {
+            patch['start'] = { dateTime: params.startTime, timeZone: params.timeZone ?? 'UTC' };
+        }
+        if (params.endTime !== undefined) {
+            patch['end'] = { dateTime: params.endTime, timeZone: params.timeZone ?? 'UTC' };
+        }
+        if (params.location !== undefined) {
+            patch['location'] = { displayName: params.location };
+        }
+        if (params.attendees !== undefined) {
+            patch['attendees'] = params.attendees.map((addr) => ({
+                emailAddress: { address: addr },
+                type: 'required',
+            }));
+        }
+        return await client.api(`/users/${email}/events/${eventId}`).patch(patch);
+    }
+    catch (err) {
+        throw mapGraphError(err, 'update_event');
+    }
+}

package/dist/graph/clientFactory.js

@@ -0,0 +1,8 @@
+import { Client } from '@microsoft/microsoft-graph-client';
+export function createGraphClient(accessToken) {
+    return Client.init({
+        authProvider: (done) => {
+            done(null, accessToken);
+        },
+    });
+}

package/dist/graph/email.js

@@ -0,0 +1,129 @@
+import { mapGraphError } from '../utils/errors.js';
+export async function listFolders(client, email, params) {
+    try {
+        const basePath = params.parentFolderId
+            ? `/users/${email}/mailFolders/${params.parentFolderId}/childFolders`
+            : `/users/${email}/mailFolders`;
+        const response = await client
+            .api(basePath)
+            .select('id,displayName,totalItemCount,unreadItemCount,childFolderCount')
+            .top(100)
+            .get();
+        return response;
+    }
+    catch (err) {
+        throw mapGraphError(err, 'list_folders');
+    }
+}
+export async function listMessages(client, email, params) {
+    try {
+        // Body search requires $search which cannot be combined with $filter.
+        // When bodySearch is provided alongside date/sender filters, we use $search
+        // for the body keyword and apply date/sender filtering client-side on the results.
+        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')
+            .top(params.maxResults)
+            .orderby('receivedDateTime desc');
+        if (params.bodySearch) {
+            // $search mode: body keyword search. Date/sender applied client-side below.
+            req = req.search(`"body:${params.bodySearch}"`);
+        }
+        else {
+            // $filter mode: supports date range and sender.
+            const filters = [];
+            if (params.startDate)
+                filters.push(`receivedDateTime ge ${params.startDate}`);
+            if (params.endDate)
+                filters.push(`receivedDateTime le ${params.endDate}`);
+            if (params.sender)
+                filters.push(`from/emailAddress/address eq '${params.sender}'`);
+            if (params.subject)
+                filters.push(`contains(subject,'${params.subject.replace(/'/g, "''")}')`);
+            if (filters.length > 0)
+                req = req.filter(filters.join(' and '));
+        }
+        const response = await req.get();
+        // Client-side post-filter when bodySearch was used with date/sender constraints
+        if (params.bodySearch && (params.startDate || params.endDate || params.sender)) {
+            const filtered = (response.value ?? []).filter((msg) => {
+                const received = new Date(msg['receivedDateTime']).getTime();
+                if (params.startDate && received < new Date(params.startDate).getTime())
+                    return false;
+                if (params.endDate && received > new Date(params.endDate).getTime())
+                    return false;
+                if (params.sender) {
+                    const from = msg['from']
+                        ?.emailAddress?.address?.toLowerCase();
+                    if (from !== params.sender.toLowerCase())
+                        return false;
+                }
+                return true;
+            });
+            return { value: filtered };
+        }
+        return response;
+    }
+    catch (err) {
+        throw mapGraphError(err, 'list_messages');
+    }
+}
+export async function getMessage(client, email, messageId, includeBody) {
+    try {
+        const select = includeBody
+            ? 'id,subject,from,toRecipients,ccRecipients,body,receivedDateTime,hasAttachments,isRead'
+            : 'id,subject,from,toRecipients,ccRecipients,receivedDateTime,hasAttachments,isRead';
+        return await client
+            .api(`/users/${email}/messages/${messageId}`)
+            .select(select)
+            .get();
+    }
+    catch (err) {
+        throw mapGraphError(err, 'get_message');
+    }
+}
+export async function sendMessage(client, email, params) {
+    try {
+        const toRecipients = params.to.map((addr) => ({ emailAddress: { address: addr } }));
+        const ccRecipients = (params.cc ?? []).map((addr) => ({ emailAddress: { address: addr } }));
+        const bccRecipients = (params.bcc ?? []).map((addr) => ({ emailAddress: { address: addr } }));
+        await client.api(`/users/${email}/sendMail`).post({
+            message: {
+                subject: params.subject,
+                body: { contentType: params.bodyType === 'html' ? 'HTML' : 'Text', content: params.body },
+                toRecipients,
+                ...(ccRecipients.length > 0 && { ccRecipients }),
+                ...(bccRecipients.length > 0 && { bccRecipients }),
+            },
+            saveToSentItems: params.saveToSent,
+        });
+    }
+    catch (err) {
+        throw mapGraphError(err, 'send_message');
+    }
+}
+export async function replyToMessage(client, email, messageId, params) {
+    try {
+        const endpoint = params.replyAll
+            ? `/users/${email}/messages/${messageId}/replyAll`
+            : `/users/${email}/messages/${messageId}/reply`;
+        await client.api(endpoint).post({
+            message: {},
+            comment: params.body,
+        });
+    }
+    catch (err) {
+        throw mapGraphError(err, 'reply_message');
+    }
+}
+export async function moveMessage(client, email, messageId, params) {
+    try {
+        return await client.api(`/users/${email}/messages/${messageId}/move`).post({
+            destinationId: params.destinationFolderId,
+        });
+    }
+    catch (err) {
+        throw mapGraphError(err, 'move_message');
+    }
+}

package/dist/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig } from './config/loader.js';
+import { TokenCache } from './auth/TokenCache.js';
+import { AuthManager } from './auth/AuthManager.js';
+import { registerAllTools } from './tools/registry.js';
+import { logger } from './utils/logger.js';
+async function main() {
+    // 1. Load and validate config — aborts if invalid
+    const config = loadConfig();
+    logger.info('Config loaded', { accounts: config.accounts.map((a) => a.id) });
+    // 2. Initialise MSAL clients (one per account, in-memory token cache)
+    const tokenCache = new TokenCache(config);
+    const auth = new AuthManager(tokenCache);
+    // 3. Create MCP server and register all tools
+    const server = new McpServer({
+        name: '@teamnetwork/m365-mcp-server',
+        version: '1.0.0',
+    });
+    registerAllTools(server, config, auth);
+    // 4. Connect via stdio transport (Claude Desktop / Claude Code)
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info('M365 MCP server running on stdio');
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal: ${err.message ?? String(err)}\n`);
+    process.exit(1);
+});

package/dist/middleware/readonlyGuard.js

@@ -0,0 +1,29 @@
+import { ToolError } from '../utils/errors.js';
+/**
+ * Asserts that the given mailbox is configured and is NOT readonly.
+ * Must be called at the top of every write-path tool handler, before any Graph call.
+ */
+export function assertWritable(config, accountId, mailbox) {
+    const account = config.accounts.find((a) => a.id === accountId);
+    if (!account) {
+        throw new ToolError(`Unknown account ID: "${accountId}". Check your config file.`, 'CONFIG_ERROR');
+    }
+    const mbConfig = account.mailboxes.find((m) => m.email.toLowerCase() === mailbox.toLowerCase());
+    if (!mbConfig) {
+        throw new ToolError(`Mailbox "${mailbox}" is not configured for account "${accountId}".`, 'CONFIG_ERROR');
+    }
+    if (mbConfig.readonly) {
+        throw new ToolError(`Mailbox "${mailbox}" is configured as read-only — write operations are not permitted.`, 'READONLY_VIOLATION');
+    }
+}
+/** Asserts that the given mailbox is configured (readable). Shared helper for read tools. */
+export function assertMailboxConfigured(config, accountId, mailbox) {
+    const account = config.accounts.find((a) => a.id === accountId);
+    if (!account) {
+        throw new ToolError(`Unknown account ID: "${accountId}". Check your config file.`, 'CONFIG_ERROR');
+    }
+    const mbConfig = account.mailboxes.find((m) => m.email.toLowerCase() === mailbox.toLowerCase());
+    if (!mbConfig) {
+        throw new ToolError(`Mailbox "${mailbox}" is not configured for account "${accountId}".`, 'CONFIG_ERROR');
+    }
+}

package/dist/tools/calendar/createEvent.js

@@ -0,0 +1,33 @@
+import { CreateEventSchema } from '../schemas.js';
+import { createGraphClient } from '../../graph/clientFactory.js';
+import { createEvent } from '../../graph/calendar.js';
+import { assertWritable } from '../../middleware/readonlyGuard.js';
+import { errorResponse } from '../../utils/errors.js';
+import { logger } from '../../utils/logger.js';
+export function registerCreateEvent(server, config, auth) {
+    server.tool('create_event', 'Create a new calendar event. Requires the mailbox to be non-readonly.', CreateEventSchema.shape, async (params) => {
+        logger.info('create_event', { accountId: params.accountId, mailbox: params.mailbox });
+        try {
+            assertWritable(config, params.accountId, params.mailbox);
+            const token = await auth.getAccessToken(params.accountId);
+            const client = createGraphClient(token);
+            const result = await createEvent(client, params.mailbox, {
+                subject: params.subject,
+                bodyType: params.bodyType,
+                startTime: params.startTime,
+                endTime: params.endTime,
+                timeZone: params.timeZone,
+                isOnlineMeeting: params.isOnlineMeeting,
+                ...(params.calendarId !== undefined && { calendarId: params.calendarId }),
+                ...(params.body !== undefined && { body: params.body }),
+                ...(params.location !== undefined && { location: params.location }),
+                ...(params.attendees !== undefined && { attendees: params.attendees }),
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            logger.error('create_event failed', { accountId: params.accountId, mailbox: params.mailbox });
+            return errorResponse(err);
+        }
+    });
+}

package/dist/tools/calendar/getEvent.js

@@ -0,0 +1,22 @@
+import { GetEventSchema } from '../schemas.js';
+import { createGraphClient } from '../../graph/clientFactory.js';
+import { getEvent } from '../../graph/calendar.js';
+import { assertMailboxConfigured } from '../../middleware/readonlyGuard.js';
+import { errorResponse } from '../../utils/errors.js';
+import { logger } from '../../utils/logger.js';
+export function registerGetEvent(server, config, auth) {
+    server.tool('get_event', 'Get full details of a specific calendar event by ID.', GetEventSchema.shape, async (params) => {
+        logger.info('get_event', { 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 getEvent(client, params.mailbox, params.eventId);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            logger.error('get_event failed', { accountId: params.accountId, mailbox: params.mailbox });
+            return errorResponse(err);
+        }
+    });
+}

package/dist/tools/calendar/listCalendars.js

@@ -0,0 +1,22 @@
+import { ListCalendarsSchema } from '../schemas.js';
+import { createGraphClient } from '../../graph/clientFactory.js';
+import { listCalendars } from '../../graph/calendar.js';
+import { assertMailboxConfigured } from '../../middleware/readonlyGuard.js';
+import { errorResponse } from '../../utils/errors.js';
+import { logger } from '../../utils/logger.js';
+export function registerListCalendars(server, config, auth) {
+    server.tool('list_calendars', 'List all calendars for a mailbox.', ListCalendarsSchema.shape, async (params) => {
+        logger.info('list_calendars', { 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 listCalendars(client, params.mailbox);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            logger.error('list_calendars failed', { accountId: params.accountId, mailbox: params.mailbox });
+            return errorResponse(err);
+        }
+    });
+}

package/dist/tools/calendar/listEvents.js

@@ -0,0 +1,27 @@
+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 { logger } from '../../utils/logger.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);
+            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,
+                ...(params.calendarId !== undefined && { calendarId: params.calendarId }),
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            logger.error('list_events failed', { accountId: params.accountId, mailbox: params.mailbox });
+            return errorResponse(err);
+        }
+    });
+}

package/dist/tools/calendar/updateEvent.js

@@ -0,0 +1,31 @@
+import { UpdateEventSchema } from '../schemas.js';
+import { createGraphClient } from '../../graph/clientFactory.js';
+import { updateEvent } from '../../graph/calendar.js';
+import { assertWritable } from '../../middleware/readonlyGuard.js';
+import { errorResponse } from '../../utils/errors.js';
+import { logger } from '../../utils/logger.js';
+export function registerUpdateEvent(server, config, auth) {
+    server.tool('update_event', 'Update an existing calendar event. Only provided fields are changed. Requires the mailbox to be non-readonly.', UpdateEventSchema.shape, async (params) => {
+        logger.info('update_event', { accountId: params.accountId, mailbox: params.mailbox });
+        try {
+            assertWritable(config, params.accountId, params.mailbox);
+            const token = await auth.getAccessToken(params.accountId);
+            const client = createGraphClient(token);
+            const result = await updateEvent(client, params.mailbox, params.eventId, {
+                ...(params.subject !== undefined && { subject: params.subject }),
+                ...(params.body !== undefined && { body: params.body }),
+                ...(params.bodyType !== undefined && { bodyType: params.bodyType }),
+                ...(params.startTime !== undefined && { startTime: params.startTime }),
+                ...(params.endTime !== undefined && { endTime: params.endTime }),
+                ...(params.timeZone !== undefined && { timeZone: params.timeZone }),
+                ...(params.location !== undefined && { location: params.location }),
+                ...(params.attendees !== undefined && { attendees: params.attendees }),
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            logger.error('update_event failed', { accountId: params.accountId, mailbox: params.mailbox });
+            return errorResponse(err);
+        }
+    });
+}

package/dist/tools/email/getMessage.js

@@ -0,0 +1,22 @@
+import { GetMessageSchema } from '../schemas.js';
+import { createGraphClient } from '../../graph/clientFactory.js';
+import { getMessage } from '../../graph/email.js';
+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) => {
+        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);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            logger.error('get_message failed', { accountId: params.accountId, mailbox: params.mailbox });
+            return errorResponse(err);
+        }
+    });
+}

package/dist/tools/email/listFolders.js

@@ -0,0 +1,24 @@
+import { ListFoldersSchema } from '../schemas.js';
+import { createGraphClient } from '../../graph/clientFactory.js';
+import { listFolders } from '../../graph/email.js';
+import { assertMailboxConfigured } from '../../middleware/readonlyGuard.js';
+import { errorResponse } from '../../utils/errors.js';
+import { logger } from '../../utils/logger.js';
+export function registerListFolders(server, config, auth) {
+    server.tool('list_folders', 'List mail folders for a mailbox. Provide parentFolderId to list child folders.', ListFoldersSchema.shape, async (params) => {
+        logger.info('list_folders', { 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 listFolders(client, params.mailbox, {
+                ...(params.parentFolderId !== undefined && { parentFolderId: params.parentFolderId }),
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            logger.error('list_folders failed', { accountId: params.accountId, mailbox: params.mailbox });
+            return errorResponse(err);
+        }
+    });
+}

package/dist/tools/email/listMailboxes.js

@@ -0,0 +1,22 @@
+import { ListMailboxesSchema } from '../schemas.js';
+import { logger } from '../../utils/logger.js';
+export function registerListMailboxes(server, config) {
+    server.tool('list_mailboxes', 'List all configured accounts and their mailboxes, including each mailbox\'s read-only status.', ListMailboxesSchema.shape, async (params) => {
+        logger.info('list_mailboxes', { accountId: params.accountId });
+        const accounts = params.accountId
+            ? config.accounts.filter((a) => a.id === params.accountId)
+            : config.accounts;
+        const result = accounts.map((a) => ({
+            id: a.id,
+            displayName: a.displayName,
+            mailboxes: a.mailboxes.map((m) => ({
+                email: m.email,
+                displayName: m.displayName,
+                readonly: m.readonly,
+            })),
+        }));
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}

package/dist/tools/email/listMessages.js

@@ -0,0 +1,35 @@
+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 { logger } from '../../utils/logger.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', {
+            accountId: params.accountId,
+            mailbox: params.mailbox,
+            folderId: params.folderId,
+            maxResults: params.maxResults,
+        });
+        try {
+            assertMailboxConfigured(config, params.accountId, params.mailbox);
+            const token = await auth.getAccessToken(params.accountId);
+            const client = createGraphClient(token);
+            const result = await listMessages(client, params.mailbox, {
+                folderId: params.folderId,
+                maxResults: params.maxResults,
+                ...(params.startDate !== undefined && { startDate: params.startDate }),
+                ...(params.endDate !== undefined && { endDate: params.endDate }),
+                ...(params.subject !== undefined && { subject: params.subject }),
+                ...(params.bodySearch !== undefined && { bodySearch: params.bodySearch }),
+                ...(params.sender !== undefined && { sender: params.sender }),
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            logger.error('list_messages failed', { accountId: params.accountId, mailbox: params.mailbox });
+            return errorResponse(err);
+        }
+    });
+}

package/dist/tools/email/moveMessage.js

@@ -0,0 +1,24 @@
+import { MoveMessageSchema } from '../schemas.js';
+import { createGraphClient } from '../../graph/clientFactory.js';
+import { moveMessage } from '../../graph/email.js';
+import { assertWritable } from '../../middleware/readonlyGuard.js';
+import { errorResponse } from '../../utils/errors.js';
+import { logger } from '../../utils/logger.js';
+export function registerMoveMessage(server, config, auth) {
+    server.tool('move_message', 'Move an email message to a different folder. Requires the mailbox to be non-readonly.', MoveMessageSchema.shape, async (params) => {
+        logger.info('move_message', { accountId: params.accountId, mailbox: params.mailbox });
+        try {
+            assertWritable(config, params.accountId, params.mailbox);
+            const token = await auth.getAccessToken(params.accountId);
+            const client = createGraphClient(token);
+            const result = await moveMessage(client, params.mailbox, params.messageId, {
+                destinationFolderId: params.destinationFolderId,
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            logger.error('move_message failed', { accountId: params.accountId, mailbox: params.mailbox });
+            return errorResponse(err);
+        }
+    });
+}

package/dist/tools/email/replyMessage.js

@@ -0,0 +1,26 @@
+import { ReplyMessageSchema } from '../schemas.js';
+import { createGraphClient } from '../../graph/clientFactory.js';
+import { replyToMessage } from '../../graph/email.js';
+import { assertWritable } from '../../middleware/readonlyGuard.js';
+import { errorResponse } from '../../utils/errors.js';
+import { logger } from '../../utils/logger.js';
+export function registerReplyMessage(server, config, auth) {
+    server.tool('reply_message', 'Reply to an email message. Use replyAll to reply to all recipients. Requires the mailbox to be non-readonly.', ReplyMessageSchema.shape, async (params) => {
+        logger.info('reply_message', { accountId: params.accountId, mailbox: params.mailbox, replyAll: params.replyAll });
+        try {
+            assertWritable(config, params.accountId, params.mailbox);
+            const token = await auth.getAccessToken(params.accountId);
+            const client = createGraphClient(token);
+            await replyToMessage(client, params.mailbox, params.messageId, {
+                body: params.body,
+                bodyType: params.bodyType,
+                replyAll: params.replyAll,
+            });
+            return { content: [{ type: 'text', text: `Reply sent successfully.` }] };
+        }
+        catch (err) {
+            logger.error('reply_message failed', { accountId: params.accountId, mailbox: params.mailbox });
+            return errorResponse(err);
+        }
+    });
+}

package/dist/tools/email/sendMessage.js

@@ -0,0 +1,30 @@
+import { SendMessageSchema } from '../schemas.js';
+import { createGraphClient } from '../../graph/clientFactory.js';
+import { sendMessage } from '../../graph/email.js';
+import { assertWritable } from '../../middleware/readonlyGuard.js';
+import { errorResponse } from '../../utils/errors.js';
+import { logger } from '../../utils/logger.js';
+export function registerSendMessage(server, config, auth) {
+    server.tool('send_message', 'Send an email from a configured mailbox. Requires the mailbox to be non-readonly.', SendMessageSchema.shape, async (params) => {
+        logger.info('send_message', { accountId: params.accountId, mailbox: params.mailbox });
+        try {
+            assertWritable(config, params.accountId, params.mailbox);
+            const token = await auth.getAccessToken(params.accountId);
+            const client = createGraphClient(token);
+            await sendMessage(client, params.mailbox, {
+                to: params.to,
+                subject: params.subject,
+                body: params.body,
+                bodyType: params.bodyType,
+                saveToSent: params.saveToSent,
+                ...(params.cc !== undefined && { cc: params.cc }),
+                ...(params.bcc !== undefined && { bcc: params.bcc }),
+            });
+            return { content: [{ type: 'text', text: 'Message sent successfully.' }] };
+        }
+        catch (err) {
+            logger.error('send_message failed', { accountId: params.accountId, mailbox: params.mailbox });
+            return errorResponse(err);
+        }
+    });
+}

package/dist/tools/registry.js

@@ -0,0 +1,35 @@
+// Email tools
+import { registerListMailboxes } from './email/listMailboxes.js';
+import { registerListFolders } from './email/listFolders.js';
+import { registerListMessages } from './email/listMessages.js';
+import { registerGetMessage } from './email/getMessage.js';
+import { registerSendMessage } from './email/sendMessage.js';
+import { registerReplyMessage } from './email/replyMessage.js';
+import { registerMoveMessage } from './email/moveMessage.js';
+// Calendar tools
+import { registerListCalendars } from './calendar/listCalendars.js';
+import { registerListEvents } from './calendar/listEvents.js';
+import { registerGetEvent } from './calendar/getEvent.js';
+import { registerCreateEvent } from './calendar/createEvent.js';
+import { registerUpdateEvent } from './calendar/updateEvent.js';
+function registerEmailTools(server, config, auth) {
+    registerListMailboxes(server, config);
+    registerListFolders(server, config, auth);
+    registerListMessages(server, config, auth);
+    registerGetMessage(server, config, auth);
+    registerSendMessage(server, config, auth);
+    registerReplyMessage(server, config, auth);
+    registerMoveMessage(server, config, auth);
+}
+function registerCalendarTools(server, config, auth) {
+    registerListCalendars(server, config, auth);
+    registerListEvents(server, config, auth);
+    registerGetEvent(server, config, auth);
+    registerCreateEvent(server, config, auth);
+    registerUpdateEvent(server, config, auth);
+}
+export function registerAllTools(server, config, auth) {
+    registerEmailTools(server, config, auth);
+    registerCalendarTools(server, config, auth);
+    // Future: registerTeamsTools(server, config, auth);
+}

package/dist/tools/schemas.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+// ── Common ─────────────────────────────────────────────────────────────────
+const AccountMailbox = z.object({
+    accountId: z.string().describe('Account ID as defined in the config file'),
+    mailbox: z.string().email().describe('Mailbox email address as defined in the config file'),
+});
+// ── Email tools ────────────────────────────────────────────────────────────
+export const ListMailboxesSchema = z.object({
+    accountId: z.string().optional().describe('Filter to a specific account ID. Omit to list all accounts and their mailboxes.'),
+});
+export const ListFoldersSchema = AccountMailbox.extend({
+    parentFolderId: z.string().optional().describe('ID of the parent folder to list child folders from. Omit for top-level folders.'),
+});
+export const ListMessagesSchema = AccountMailbox.extend({
+    folderId: z.string().default('Inbox').describe('Folder ID or well-known name (e.g. "Inbox", "SentItems", "Drafts")'),
+    startDate: z.string().datetime().optional().describe('Filter messages received on or after this ISO 8601 datetime'),
+    endDate: z.string().datetime().optional().describe('Filter messages received on or before this ISO 8601 datetime'),
+    subject: z.string().optional().describe('Filter messages whose subject contains this string (ignored when bodySearch is set)'),
+    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)'),
+});
+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'),
+});
+export const SendMessageSchema = AccountMailbox.extend({
+    to: z.array(z.string().email()).min(1).describe('List of recipient email addresses'),
+    cc: z.array(z.string().email()).optional().describe('CC recipients'),
+    bcc: z.array(z.string().email()).optional().describe('BCC recipients'),
+    subject: z.string().min(1).describe('Message subject'),
+    body: z.string().describe('Message body content'),
+    bodyType: z.enum(['text', 'html']).default('text').describe('Body content type'),
+    saveToSent: z.boolean().default(true).describe('Whether to save the message to Sent Items'),
+});
+export const ReplyMessageSchema = AccountMailbox.extend({
+    messageId: z.string().describe('The ID of the message to reply to'),
+    body: z.string().describe('Reply body content'),
+    bodyType: z.enum(['text', 'html']).default('text'),
+    replyAll: z.boolean().default(false).describe('If true, reply to all recipients; otherwise reply only to sender'),
+});
+export const MoveMessageSchema = AccountMailbox.extend({
+    messageId: z.string().describe('The ID of the message to move'),
+    destinationFolderId: z.string().describe('The destination folder ID or well-known name (e.g. "DeletedItems")'),
+});
+// ── Calendar tools ─────────────────────────────────────────────────────────
+export const ListCalendarsSchema = AccountMailbox;
+export const ListEventsSchema = AccountMailbox.extend({
+    calendarId: z.string().optional().describe('Calendar ID. Omit to use the default calendar.'),
+    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),
+});
+export const GetEventSchema = AccountMailbox.extend({
+    eventId: z.string().describe('The event ID'),
+    calendarId: z.string().optional().describe('Calendar ID. Omit to search across all calendars.'),
+});
+export const CreateEventSchema = AccountMailbox.extend({
+    calendarId: z.string().optional().describe('Calendar ID. Omit to create in the default calendar.'),
+    subject: z.string().min(1).describe('Event subject / title'),
+    body: z.string().optional().describe('Event description / body'),
+    bodyType: z.enum(['text', 'html']).default('text'),
+    startTime: z.string().datetime().describe('Event start time (ISO 8601 with timezone offset)'),
+    endTime: z.string().datetime().describe('Event end time (ISO 8601 with timezone offset)'),
+    timeZone: z.string().default('UTC').describe('IANA timezone name, e.g. "Pacific/Auckland"'),
+    location: z.string().optional().describe('Location display name'),
+    attendees: z.array(z.string().email()).optional().describe('List of attendee email addresses'),
+    isOnlineMeeting: z.boolean().default(false).describe('Whether to create an online meeting link'),
+});
+export const UpdateEventSchema = AccountMailbox.extend({
+    eventId: z.string().describe('The ID of the event to update'),
+    subject: z.string().optional(),
+    body: z.string().optional(),
+    bodyType: z.enum(['text', 'html']).optional(),
+    startTime: z.string().datetime().optional(),
+    endTime: z.string().datetime().optional(),
+    timeZone: z.string().optional(),
+    location: z.string().optional(),
+    attendees: z.array(z.string().email()).optional(),
+});

package/dist/utils/errors.js

@@ -0,0 +1,48 @@
+export class ToolError extends Error {
+    code;
+    retryable;
+    constructor(message, code, retryable = false) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = 'ToolError';
+    }
+}
+export function mapGraphError(err, context) {
+    if (err instanceof ToolError)
+        return err;
+    const status = err?.['statusCode'];
+    const msg = err?.message ?? String(err);
+    // Never include response body in mapped errors — it may contain email/calendar content
+    switch (status) {
+        case 400:
+            return new ToolError(`Bad request to Graph API (${context}): ${msg}`, 'GRAPH_BAD_REQUEST');
+        case 401:
+            return new ToolError(`Authentication failed (${context}) — verify tenant ID, client ID, and client secret`, 'GRAPH_UNAUTHORIZED');
+        case 403:
+            return new ToolError(`Access denied (${context}) — verify ApplicationAccessPolicy is configured and app permissions are admin-consented`, 'GRAPH_FORBIDDEN');
+        case 404:
+            return new ToolError(`Resource not found (${context})`, 'GRAPH_NOT_FOUND');
+        case 429: {
+            const headers = err?.['headers'];
+            const retryAfter = headers?.['retry-after'] ?? 'unknown';
+            return new ToolError(`Graph API rate limit hit (${context}). Retry after ${retryAfter}s`, 'GRAPH_RATE_LIMIT', true);
+        }
+        case 503:
+        case 504:
+            return new ToolError(`Graph API service unavailable (${context}) — try again shortly`, 'GRAPH_UNAVAILABLE', true);
+        default:
+            if (status !== undefined) {
+                return new ToolError(`Graph API error ${status} (${context})`, 'GRAPH_ERROR');
+            }
+            return new ToolError(`Unexpected error (${context}): ${msg}`, 'UNKNOWN');
+    }
+}
+/** Format a tool error response for the MCP SDK */
+export function errorResponse(err) {
+    const toolErr = err instanceof ToolError ? err : mapGraphError(err, 'unknown');
+    return {
+        content: [{ type: 'text', text: toolErr.message }],
+        isError: true,
+    };
+}

package/dist/utils/logger.js

@@ -0,0 +1,32 @@
+// Structured logger with scrubbing of secrets, tokens, and email body content.
+// Only tool name, account ID, mailbox address, status codes, and timestamps are safe to log.
+const SCRUB_PATTERNS = [
+    /clientSecret['":\s]+[^\s,}"']+/gi,
+    /Bearer\s+[A-Za-z0-9\-_.]+/gi,
+    /accessToken['":\s]+[A-Za-z0-9\-_.]+/gi,
+    /"content"\s*:\s*"[^"]{50,}"/gi, // long content strings (likely email body)
+    /"body"\s*:\s*\{[^}]{20,}\}/gi, // body objects
+];
+function scrub(value) {
+    let result = value;
+    for (const pattern of SCRUB_PATTERNS) {
+        result = result.replace(pattern, '[REDACTED]');
+    }
+    return result;
+}
+function format(level, message, meta) {
+    const ts = new Date().toISOString();
+    const metaStr = meta ? ' ' + scrub(JSON.stringify(meta)) : '';
+    return `[${ts}] [${level}] ${message}${metaStr}`;
+}
+export const logger = {
+    info(message, meta) {
+        process.stderr.write(format('INFO', message, meta) + '\n');
+    },
+    warn(message, meta) {
+        process.stderr.write(format('WARN', message, meta) + '\n');
+    },
+    error(message, meta) {
+        process.stderr.write(format('ERROR', message, meta) + '\n');
+    },
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@teamnetwork/m365-mcp-server",
+  "version": "1.0.0",
+  "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",
+  "bin": {
+    "m365-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "config.example.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "microsoft-365",
+    "m365",
+    "outlook",
+    "email",
+    "calendar",
+    "microsoft-graph",
+    "claude",
+    "ai"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@azure/msal-node": "^2.16.0",
+    "@microsoft/microsoft-graph-client": "^3.0.7",
+    "@modelcontextprotocol/sdk": "^1.10.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.10.0",
+    "typescript": "^5.4.0"
+  }
+}