@masonator/m365-mcp 0.1.0

package/dist/lib/auth.js

@@ -0,0 +1,333 @@
+import { mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createServer } from 'node:net';
+import { createServer as createHttpServer } from 'node:http';
+import { URL } from 'node:url';
+import { randomBytes } from 'node:crypto';
+import { execFile } from 'node:child_process';
+const TOKEN_FILENAME = 'tokens.json';
+const EXPIRY_BUFFER_MS = 120000; // 2 minutes
+const AUTH_TIMEOUT_MS = 300000; // 5 minutes
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#x27;');
+}
+export const SCOPES = [
+    'openid',
+    'profile',
+    'email',
+    'offline_access',
+    'User.Read',
+    'Calendars.Read',
+    'Mail.Read',
+    'Chat.Read',
+    'Files.Read',
+    'OnlineMeetingTranscript.Read.All',
+    'Sites.Read.All',
+];
+/**
+ * Returns the config directory for m365-mcp.
+ * Respects XDG_CONFIG_HOME, falls back to ~/.config/m365-mcp.
+ * Creates the directory (recursively) if it doesn't exist.
+ */
+export function getConfigDir() {
+    const base = process.env['XDG_CONFIG_HOME'] || join(homedir(), '.config');
+    const configDir = join(base, 'm365-mcp');
+    mkdirSync(configDir, { recursive: true });
+    return configDir;
+}
+/**
+ * Loads tokens from tokens.json in the given config directory.
+ * Returns null if the file doesn't exist or contains invalid JSON.
+ */
+export function loadTokens(configDir) {
+    const dir = configDir ?? getConfigDir();
+    const filePath = join(dir, TOKEN_FILENAME);
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Saves tokens to tokens.json in the given config directory.
+ * Sets file permissions to 0o600 (user read/write only).
+ */
+export function saveTokens(tokens, configDir) {
+    const dir = configDir ?? getConfigDir();
+    const filePath = join(dir, TOKEN_FILENAME);
+    writeFileSync(filePath, JSON.stringify(tokens, null, 2), { mode: 0o600, encoding: 'utf-8' });
+}
+/**
+ * Deletes tokens.json from the given config directory.
+ * Does nothing if the file doesn't exist.
+ */
+export function deleteTokens(configDir) {
+    const dir = configDir ?? getConfigDir();
+    const filePath = join(dir, TOKEN_FILENAME);
+    try {
+        unlinkSync(filePath);
+    }
+    catch {
+        // File doesn't exist — nothing to do
+    }
+}
+/**
+ * Returns true if the token expires within 2 minutes (120 000 ms safety buffer).
+ */
+export function isTokenExpired(tokens) {
+    const expiresAt = new Date(tokens.expires_at).getTime();
+    return expiresAt < Date.now() + EXPIRY_BUFFER_MS;
+}
+/**
+ * Loads auth configuration from environment variables.
+ * Throws with a clear message if any required variable is missing.
+ */
+export function loadAuthConfig() {
+    const clientId = process.env['MS365_MCP_CLIENT_ID'];
+    const clientSecret = process.env['MS365_MCP_CLIENT_SECRET'];
+    const tenantId = process.env['MS365_MCP_TENANT_ID'];
+    const missing = [];
+    if (!clientId)
+        missing.push('MS365_MCP_CLIENT_ID');
+    if (!clientSecret)
+        missing.push('MS365_MCP_CLIENT_SECRET');
+    if (!tenantId)
+        missing.push('MS365_MCP_TENANT_ID');
+    if (missing.length > 0) {
+        throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
+    }
+    return {
+        clientId: clientId,
+        clientSecret: clientSecret,
+        tenantId: tenantId,
+    };
+}
+/**
+ * Finds an available port by binding to port 0 and reading the assigned port.
+ * @internal Exported for testing only.
+ */
+export function findAvailablePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.listen(0, () => {
+            const addr = srv.address();
+            if (addr && typeof addr === 'object') {
+                const port = addr.port;
+                srv.close(() => resolve(port));
+            }
+            else {
+                /* istanbul ignore next -- defensive branch never reached with port 0 */
+                srv.close(() => reject(new Error('Could not determine port')));
+            }
+        });
+        srv.on('error', reject);
+    });
+}
+/**
+ * Opens a URL in the default browser.
+ * Falls back to printing the URL to stderr if the browser cannot be opened.
+ * @internal Exported for testing only.
+ */
+export function openBrowser(url) {
+    /* istanbul ignore next -- platform-specific browser launch */
+    const platform = process.platform;
+    try {
+        /* istanbul ignore next */
+        if (platform === 'darwin') {
+            execFile('open', [url]);
+        }
+        else if (platform === 'win32') {
+            execFile('cmd', ['/c', 'start', '', url]);
+        }
+        else {
+            execFile('xdg-open', [url]);
+        }
+    }
+    catch {
+        process.stderr.write(`Could not open browser. Please visit:\n${url}\n`);
+    }
+}
+/**
+ * Exchanges an authorization code for tokens via Azure AD token endpoint.
+ * @internal Exported for testing only.
+ */
+export async function exchangeCodeForTokens(config, code, redirectUri) {
+    const tokenUrl = `https://login.microsoftonline.com/${config.tenantId}/oauth2/v2.0/token`;
+    const body = new URLSearchParams({
+        grant_type: 'authorization_code',
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+        code,
+        redirect_uri: redirectUri,
+    });
+    const response = await fetch(tokenUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: body.toString(),
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Token exchange failed (${response.status}): ${errorText}`);
+    }
+    const data = (await response.json());
+    return {
+        access_token: data.access_token,
+        refresh_token: data.refresh_token,
+        expires_at: new Date(Date.now() + data.expires_in * 1000).toISOString(),
+        scopes: data.scope,
+    };
+}
+/**
+ * Starts an HTTP server on the given port and waits for the OAuth callback.
+ * Returns the authorization code from the callback query string.
+ * @internal Exported for testing only.
+ */
+export function waitForAuthCallback(port, expectedState, timeoutMs = AUTH_TIMEOUT_MS) {
+    let httpServer;
+    const promise = new Promise((resolve, reject) => {
+        const closeServer = () => {
+            httpServer.close();
+            httpServer.closeAllConnections();
+        };
+        const timeout = setTimeout(() => {
+            closeServer();
+            reject(new Error('Authentication timed out after 5 minutes. Please try again.'));
+        }, timeoutMs);
+        httpServer = createHttpServer((req, res) => {
+            if (!req.url?.startsWith('/callback')) {
+                res.writeHead(404);
+                res.end('Not found');
+                return;
+            }
+            const url = new URL(req.url, `http://localhost:${port}`);
+            const callbackState = url.searchParams.get('state');
+            const callbackCode = url.searchParams.get('code');
+            const error = url.searchParams.get('error');
+            if (error) {
+                const errorDesc = url.searchParams.get('error_description') || error;
+                const safeDesc = escapeHtml(errorDesc);
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end(`<!DOCTYPE html><html><body style="font-family:sans-serif;text-align:center;padding:40px"><h1>Sign-in failed</h1><p>${safeDesc}</p></body></html>`);
+                clearTimeout(timeout);
+                closeServer();
+                reject(new Error(`Authentication failed: ${errorDesc}`));
+                return;
+            }
+            if (callbackState !== expectedState) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end('<!DOCTYPE html><html><body style="font-family:sans-serif;text-align:center;padding:40px"><h1>Error</h1><p>State mismatch — possible CSRF attack.</p></body></html>');
+                clearTimeout(timeout);
+                closeServer();
+                reject(new Error('State mismatch in OAuth callback'));
+                return;
+            }
+            if (!callbackCode) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end('<!DOCTYPE html><html><body style="font-family:sans-serif;text-align:center;padding:40px"><h1>Error</h1><p>No authorization code received.</p></body></html>');
+                clearTimeout(timeout);
+                closeServer();
+                reject(new Error('No authorization code in callback'));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end('<!DOCTYPE html><html><body style="font-family:sans-serif;text-align:center;padding:40px"><h1>Signed in!</h1><p>You can close this tab.</p></body></html>');
+            clearTimeout(timeout);
+            closeServer();
+            resolve(callbackCode);
+        });
+        httpServer.listen(port);
+    });
+    return { promise, server: httpServer };
+}
+/**
+ * Browser-popup + localhost-callback OAuth2 flow.
+ * Opens the browser for Microsoft 365 sign-in, listens for the callback,
+ * exchanges the authorization code for tokens, saves them, and returns the TokenData.
+ */
+export async function startAuthFlow(config) {
+    const port = await findAvailablePort();
+    const redirectUri = `http://localhost:${port}/callback`;
+    const state = randomBytes(16).toString('hex');
+    const authUrl = new URL(`https://login.microsoftonline.com/${config.tenantId}/oauth2/v2.0/authorize`);
+    authUrl.searchParams.set('client_id', config.clientId);
+    authUrl.searchParams.set('response_type', 'code');
+    authUrl.searchParams.set('redirect_uri', redirectUri);
+    authUrl.searchParams.set('scope', SCOPES.join(' '));
+    authUrl.searchParams.set('state', state);
+    process.stderr.write('Opening browser for Microsoft 365 sign-in...\n');
+    openBrowser(authUrl.toString());
+    const { promise } = waitForAuthCallback(port, state);
+    const code = await promise;
+    const tokenData = await exchangeCodeForTokens(config, code, redirectUri);
+    saveTokens(tokenData);
+    return tokenData;
+}
+/**
+ * Refreshes an access token using a refresh token.
+ * On success, saves and returns the new TokenData.
+ * On failure, deletes stored tokens and returns null.
+ */
+export async function refreshAccessToken(config, refreshToken) {
+    const tokenUrl = `https://login.microsoftonline.com/${config.tenantId}/oauth2/v2.0/token`;
+    const body = new URLSearchParams({
+        grant_type: 'refresh_token',
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+        refresh_token: refreshToken,
+    });
+    try {
+        const response = await fetch(tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: body.toString(),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            process.stderr.write(`Token refresh failed (${response.status}): ${errorText}\n`);
+            deleteTokens();
+            return null;
+        }
+        const data = (await response.json());
+        const tokenData = {
+            access_token: data.access_token,
+            refresh_token: data.refresh_token,
+            expires_at: new Date(Date.now() + data.expires_in * 1000).toISOString(),
+            scopes: data.scope,
+        };
+        saveTokens(tokenData);
+        return tokenData;
+    }
+    catch (err) {
+        process.stderr.write(`Token refresh error: ${err instanceof Error ? err.message : err}\n`);
+        deleteTokens();
+        return null;
+    }
+}
+/**
+ * Main entry point — returns a valid access token.
+ * Loads cached tokens, refreshes if expired, or starts a new auth flow if needed.
+ */
+export async function getAccessToken(config) {
+    const tokens = loadTokens();
+    if (!tokens) {
+        const newTokens = await startAuthFlow(config);
+        return newTokens.access_token;
+    }
+    if (!isTokenExpired(tokens)) {
+        return tokens.access_token;
+    }
+    const refreshed = await refreshAccessToken(config, tokens.refresh_token);
+    if (refreshed) {
+        return refreshed.access_token;
+    }
+    const newTokens = await startAuthFlow(config);
+    return newTokens.access_token;
+}

package/dist/lib/graph.d.ts

@@ -0,0 +1,20 @@
+export interface GraphError {
+    status: number;
+    message: string;
+}
+export type GraphResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: GraphError;
+};
+export interface GraphFetchOptions {
+    beta?: boolean;
+    timezone?: boolean;
+}
+/**
+ * Thin fetch wrapper for Microsoft Graph API calls.
+ * Translates HTTP errors into typed GraphError results.
+ */
+export declare function graphFetch<T>(path: string, token: string, options?: GraphFetchOptions): Promise<GraphResult<T>>;

package/dist/lib/graph.js

@@ -0,0 +1,53 @@
+/**
+ * Thin fetch wrapper for Microsoft Graph API calls.
+ * Translates HTTP errors into typed GraphError results.
+ */
+export async function graphFetch(path, token, options) {
+    const base = options?.beta
+        ? 'https://graph.microsoft.com/beta'
+        : 'https://graph.microsoft.com/v1.0';
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+    };
+    if (options?.timezone !== false) {
+        const tz = process.env.MS365_MCP_TIMEZONE || Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+        headers['Prefer'] = `outlook.timezone="${tz}"`;
+    }
+    let response;
+    try {
+        response = await fetch(`${base}${path}`, { headers });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: {
+                status: 0,
+                message: `Network error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
+    if (response.ok) {
+        const data = (await response.json());
+        return { ok: true, data };
+    }
+    const status = response.status;
+    let message;
+    switch (status) {
+        case 401:
+            message = 'Graph token expired. Use ms_auth_status to reconnect.';
+            break;
+        case 403:
+            message = 'Insufficient permissions. Check granted scopes with ms_auth_status.';
+            break;
+        case 404:
+            message = 'Resource not found. Your account may not have an Exchange Online license.';
+            break;
+        default: {
+            const text = await response.text();
+            message = `Graph API error (${status}): ${text}`;
+            break;
+        }
+    }
+    return { ok: false, error: { status, message } };
+}

package/dist/lib/tools/auth-status.d.ts

@@ -0,0 +1,15 @@
+import type { AuthConfig } from '../../types/tokens.js';
+export declare const authStatusToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {};
+    };
+};
+/**
+ * Check Microsoft 365 connection status.
+ * Handles the full lifecycle: no tokens, expired tokens, valid tokens.
+ * Triggers auth flow if not connected.
+ */
+export declare function executeAuthStatus(config: AuthConfig): Promise<string>;

package/dist/lib/tools/auth-status.js

@@ -0,0 +1,90 @@
+import { loadTokens, isTokenExpired, startAuthFlow, SCOPES } from '../auth.js';
+import { refreshAccessToken } from '../auth.js';
+import { graphFetch } from '../graph.js';
+export const authStatusToolDefinition = {
+    name: 'ms_auth_status',
+    description: 'Check Microsoft 365 connection status. If not connected, opens browser to sign in.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+    },
+};
+/**
+ * Fetches a short profile summary for the status display.
+ * Returns null if the fetch fails.
+ */
+async function fetchProfileSummary(token) {
+    const result = await graphFetch('/me', token);
+    if (!result.ok) {
+        return null;
+    }
+    return {
+        displayName: result.data.displayName || 'Unknown',
+        email: result.data.mail || result.data.userPrincipalName || 'Unknown',
+    };
+}
+/**
+ * Formats a "just signed in" status message.
+ */
+function formatJustConnected(profile) {
+    const lines = ['Status: Connected \u2713 (just signed in)'];
+    if (profile) {
+        lines.push(`User: ${profile.displayName} (${profile.email})`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Formats a full connected status message with token details.
+ */
+function formatConnectedStatus(tokens, profile) {
+    const lines = ['Status: Connected \u2713'];
+    if (profile) {
+        lines.push(`User: ${profile.displayName} (${profile.email})`);
+    }
+    lines.push(`Token expires: ${tokens.expires_at}`);
+    lines.push(`Scopes: ${tokens.scopes || SCOPES.join(' ')}`);
+    return lines.join('\n');
+}
+/**
+ * Formats an error status message.
+ */
+function formatError(message) {
+    return [
+        'Status: Not connected',
+        `Error: ${message}`,
+        'Action: Run ms_auth_status again to sign in.',
+    ].join('\n');
+}
+/**
+ * Check Microsoft 365 connection status.
+ * Handles the full lifecycle: no tokens, expired tokens, valid tokens.
+ * Triggers auth flow if not connected.
+ */
+export async function executeAuthStatus(config) {
+    try {
+        const tokens = loadTokens();
+        // No tokens — start auth flow
+        if (!tokens) {
+            process.stderr.write('Not connected. Starting auth flow...\n');
+            const newTokens = await startAuthFlow(config);
+            const profile = await fetchProfileSummary(newTokens.access_token);
+            return formatJustConnected(profile);
+        }
+        // Tokens exist but expired — try refresh
+        if (isTokenExpired(tokens)) {
+            const refreshed = await refreshAccessToken(config, tokens.refresh_token);
+            if (!refreshed) {
+                return formatError('Token expired and refresh failed. Please sign in again.');
+            }
+            const profile = await fetchProfileSummary(refreshed.access_token);
+            return formatConnectedStatus(refreshed, profile);
+        }
+        // Tokens valid — show status
+        const profile = await fetchProfileSummary(tokens.access_token);
+        return formatConnectedStatus(tokens, profile);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return formatError(message);
+    }
+}

package/dist/lib/tools/calendar.d.ts

@@ -0,0 +1,30 @@
+export declare const calendarToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            date: {
+                type: string;
+                description: string;
+            };
+            start: {
+                type: string;
+                description: string;
+            };
+            end: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};
+/**
+ * Fetches calendar events for the specified date range and returns
+ * a human-readable summary.
+ */
+export declare function executeCalendar(token: string, args: {
+    date?: string;
+    start?: string;
+    end?: string;
+}): Promise<string>;

package/dist/lib/tools/calendar.js

@@ -0,0 +1,117 @@
+import { graphFetch } from '../graph.js';
+export const calendarToolDefinition = {
+    name: 'ms_calendar',
+    description: "Fetch the user's Microsoft 365 calendar events. Defaults to today if no date params given.",
+    inputSchema: {
+        type: 'object',
+        properties: {
+            date: { type: 'string', description: 'Fetch events for a specific date (YYYY-MM-DD)' },
+            start: { type: 'string', description: 'Start of date range (ISO 8601)' },
+            end: { type: 'string', description: 'End of date range (ISO 8601)' },
+        },
+    },
+};
+/**
+ * Computes the start and end ISO strings for a given YYYY-MM-DD date.
+ */
+function dateRangeForDay(dateStr) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(dateStr))
+        return null;
+    const date = new Date(`${dateStr}T00:00:00.000Z`);
+    if (isNaN(date.getTime()))
+        return null;
+    const next = new Date(date);
+    next.setUTCDate(next.getUTCDate() + 1);
+    return { start: date.toISOString(), end: next.toISOString() };
+}
+/**
+ * Returns today's date range (local midnight to next midnight) in ISO format.
+ */
+function todayRange() {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const day = String(now.getDate()).padStart(2, '0');
+    return dateRangeForDay(`${year}-${month}-${day}`);
+}
+/**
+ * Formats a calendar event into readable multi-line text.
+ */
+function formatEvent(event) {
+    const lines = [];
+    lines.push(`## ${event.subject || 'Untitled'}`);
+    if (event.isAllDay) {
+        lines.push('Time: All day');
+    }
+    else {
+        const startTime = event.start?.dateTime || 'N/A';
+        const endTime = event.end?.dateTime || 'N/A';
+        lines.push(`Time: ${startTime} - ${endTime}`);
+    }
+    if (event.location?.displayName) {
+        lines.push(`Location: ${event.location.displayName}`);
+    }
+    if (event.organizer?.emailAddress?.name) {
+        lines.push(`Organizer: ${event.organizer.emailAddress.name}`);
+    }
+    if (event.attendees && event.attendees.length > 0) {
+        const names = event.attendees
+            .map((a) => a.emailAddress?.name)
+            .filter(Boolean)
+            .join(', ');
+        if (names) {
+            lines.push(`Attendees: ${names}`);
+        }
+    }
+    if (event.bodyPreview) {
+        lines.push(event.bodyPreview);
+    }
+    return lines.join('\n');
+}
+/**
+ * Fetches calendar events for the specified date range and returns
+ * a human-readable summary.
+ */
+export async function executeCalendar(token, args) {
+    let start;
+    let end;
+    if (args.date) {
+        const range = dateRangeForDay(args.date);
+        if (!range)
+            return 'Error: Invalid date format. Expected YYYY-MM-DD.';
+        start = range.start;
+        end = range.end;
+    }
+    else if (args.start && args.end) {
+        start = args.start;
+        end = args.end;
+    }
+    else {
+        const range = todayRange();
+        start = range.start;
+        end = range.end;
+    }
+    const select = [
+        'subject',
+        'start',
+        'end',
+        'location',
+        'attendees',
+        'isAllDay',
+        'bodyPreview',
+        'organizer',
+        'onlineMeeting',
+        'webLink',
+    ].join(',');
+    const path = `/me/calendarView?startDateTime=${start}&endDateTime=${end}` +
+        `&$orderby=start/dateTime&$top=50&$select=${select}`;
+    const result = await graphFetch(path, token, { timezone: true });
+    if (!result.ok) {
+        return `Error: ${result.error.message}`;
+    }
+    const events = result.data.value;
+    if (!events || events.length === 0) {
+        return 'No calendar events found for the specified date range.';
+    }
+    return events.map(formatEvent).join('\n\n');
+}

package/dist/lib/tools/chat.d.ts

@@ -0,0 +1,25 @@
+export declare const chatToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            chat_id: {
+                type: string;
+                description: string;
+            };
+            count: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};
+/**
+ * Fetches Teams chats or messages from a specific chat thread and returns
+ * a human-readable summary.
+ */
+export declare function executeChat(token: string, args: {
+    chat_id?: string;
+    count?: number;
+}): Promise<string>;