@littlebearapps/outlook-assistant 3.3.0

package/folder/stats.js

@@ -0,0 +1,322 @@
+/**
+ * Get folder statistics functionality
+ *
+ * Returns folder item counts and metadata for pagination planning.
+ * Supports outputVerbosity for token-efficient responses.
+ */
+const { callGraphAPI } = require('../utils/graph-api');
+const { ensureAuthenticated } = require('../auth');
+const config = require('../config');
+
+const { VERBOSITY, DEFAULT_LIMITS } = config;
+
+/**
+ * Get folder stats handler
+ * @param {object} args - Tool arguments
+ * @returns {object} - MCP response
+ */
+async function handleGetFolderStats(args) {
+  const folderName = args.folder || 'inbox';
+  const verbosity = args.outputVerbosity || VERBOSITY.STANDARD;
+
+  try {
+    const accessToken = await ensureAuthenticated();
+
+    // Resolve folder name to ID
+    const folderId = await resolveFolderName(accessToken, folderName);
+
+    if (!folderId) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Folder "${folderName}" not found.`,
+          },
+        ],
+      };
+    }
+
+    // Get folder details with full stats
+    const folder = await callGraphAPI(
+      accessToken,
+      'GET',
+      `me/mailFolders/${folderId}`,
+      null,
+      {
+        // Note: sizeInBytes is NOT available on mailFolder resource type
+        $select:
+          'id,displayName,parentFolderId,childFolderCount,totalItemCount,unreadItemCount,isHidden',
+      }
+    );
+
+    // Get recent email dates for context
+    let dateRange = null;
+    if (verbosity !== VERBOSITY.MINIMAL && folder.totalItemCount > 0) {
+      dateRange = await getEmailDateRange(accessToken, folderId);
+    }
+
+    // Format response based on verbosity
+    const formatted = formatFolderStats(folder, dateRange, verbosity);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: formatted.text,
+        },
+      ],
+      _meta: formatted.meta,
+    };
+  } catch (error) {
+    if (error.message === 'Authentication required') {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: "Authentication required. Please use the 'authenticate' tool first.",
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error getting folder stats: ${error.message}`,
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * Resolve folder name to ID
+ * @param {string} accessToken - Access token
+ * @param {string} folderName - Folder name or well-known name
+ * @returns {Promise<string|null>} - Folder ID or null
+ */
+async function resolveFolderName(accessToken, folderName) {
+  const wellKnownFolders = {
+    inbox: 'inbox',
+    sent: 'sentitems',
+    sentitems: 'sentitems',
+    'sent items': 'sentitems',
+    drafts: 'drafts',
+    deleted: 'deleteditems',
+    deleteditems: 'deleteditems',
+    'deleted items': 'deleteditems',
+    junk: 'junkemail',
+    junkemail: 'junkemail',
+    'junk email': 'junkemail',
+    spam: 'junkemail',
+    archive: 'archive',
+    outbox: 'outbox',
+  };
+
+  const normalised = folderName.toLowerCase().trim();
+
+  // Check if it's a well-known folder
+  if (wellKnownFolders[normalised]) {
+    try {
+      const response = await callGraphAPI(
+        accessToken,
+        'GET',
+        `me/mailFolders/${wellKnownFolders[normalised]}`,
+        null,
+        { $select: 'id' }
+      );
+      return response.id;
+    } catch (_error) {
+      // Fall through to search
+    }
+  }
+
+  // Search for folder by name
+  try {
+    const response = await callGraphAPI(
+      accessToken,
+      'GET',
+      'me/mailFolders',
+      null,
+      {
+        $filter: `displayName eq '${folderName}'`,
+        $select: 'id',
+      }
+    );
+
+    if (response.value && response.value.length > 0) {
+      return response.value[0].id;
+    }
+  } catch (error) {
+    console.error(`Error searching for folder: ${error.message}`);
+  }
+
+  return null;
+}
+
+/**
+ * Get date range of emails in folder
+ * @param {string} accessToken - Access token
+ * @param {string} folderId - Folder ID
+ * @returns {Promise<object|null>} - { oldest, newest } dates or null
+ */
+async function getEmailDateRange(accessToken, folderId) {
+  try {
+    // Get newest email
+    const newestResponse = await callGraphAPI(
+      accessToken,
+      'GET',
+      `me/mailFolders/${folderId}/messages`,
+      null,
+      {
+        $select: 'receivedDateTime',
+        $orderby: 'receivedDateTime desc',
+        $top: 1,
+      }
+    );
+
+    // Get oldest email
+    const oldestResponse = await callGraphAPI(
+      accessToken,
+      'GET',
+      `me/mailFolders/${folderId}/messages`,
+      null,
+      {
+        $select: 'receivedDateTime',
+        $orderby: 'receivedDateTime asc',
+        $top: 1,
+      }
+    );
+
+    const newest = newestResponse.value?.[0]?.receivedDateTime;
+    const oldest = oldestResponse.value?.[0]?.receivedDateTime;
+
+    if (newest && oldest) {
+      return { newest, oldest };
+    }
+  } catch (error) {
+    console.error(`Error getting date range: ${error.message}`);
+  }
+
+  return null;
+}
+
+/**
+ * Format folder stats based on verbosity
+ * @param {object} folder - Folder object from Graph API
+ * @param {object|null} dateRange - Date range object
+ * @param {string} verbosity - Verbosity level
+ * @returns {object} - { text, meta }
+ */
+function formatFolderStats(folder, dateRange, verbosity) {
+  const totalItems = folder.totalItemCount || 0;
+  const unreadItems = folder.unreadItemCount || 0;
+
+  // Calculate pagination info
+  const pageSize = DEFAULT_LIMITS.listEmails;
+  const totalPages = Math.ceil(totalItems / pageSize);
+
+  // Build meta object
+  const meta = {
+    folderId: folder.id,
+    folderName: folder.displayName,
+    totalItems,
+    unreadItems,
+    pageSize,
+    totalPages,
+    verbosity,
+  };
+
+  // Minimal: Just key numbers
+  if (verbosity === VERBOSITY.MINIMAL) {
+    return {
+      text: `${folder.displayName}: ${totalItems} items (${unreadItems} unread)`,
+      meta,
+    };
+  }
+
+  // Standard: Markdown table with key stats
+  if (verbosity === VERBOSITY.STANDARD) {
+    let text = `## ${folder.displayName} Statistics\n\n`;
+    text += `| Metric | Value |\n`;
+    text += `|--------|-------|\n`;
+    text += `| Total Items | ${totalItems.toLocaleString()} |\n`;
+    text += `| Unread Items | ${unreadItems.toLocaleString()} |\n`;
+    text += `| Pages (${pageSize}/page) | ${totalPages} |\n`;
+
+    if (dateRange) {
+      const newest = new Date(dateRange.newest).toLocaleDateString('en-AU');
+      const oldest = new Date(dateRange.oldest).toLocaleDateString('en-AU');
+      text += `| Date Range | ${oldest} to ${newest} |\n`;
+    }
+
+    if (totalItems > 100) {
+      text += `\n_Hint: Use list-emails-delta for efficient incremental sync of large folders._`;
+    }
+
+    return { text, meta };
+  }
+
+  // Full: All available information
+  let text = `# ${folder.displayName} - Full Statistics\n\n`;
+
+  text += `## Overview\n\n`;
+  text += `| Metric | Value |\n`;
+  text += `|--------|-------|\n`;
+  text += `| Folder ID | \`${folder.id}\` |\n`;
+  text += `| Display Name | ${folder.displayName} |\n`;
+  text += `| Total Items | ${totalItems.toLocaleString()} |\n`;
+  text += `| Unread Items | ${unreadItems.toLocaleString()} |\n`;
+  text += `| Read Items | ${(totalItems - unreadItems).toLocaleString()} |\n`;
+  text += `| Child Folders | ${folder.childFolderCount || 0} |\n`;
+  text += `| Hidden | ${folder.isHidden ? 'Yes' : 'No'} |\n`;
+
+  if (folder.parentFolderId) {
+    text += `| Parent Folder ID | \`${folder.parentFolderId}\` |\n`;
+  }
+
+  text += `\n## Pagination Planning\n\n`;
+  text += `| Setting | Value |\n`;
+  text += `|---------|-------|\n`;
+  text += `| Page Size | ${pageSize} emails |\n`;
+  text += `| Total Pages | ${totalPages} |\n`;
+  text += `| Estimated API Calls | ${totalPages} (list-emails) |\n`;
+
+  if (dateRange) {
+    const newestDate = new Date(dateRange.newest);
+    const oldestDate = new Date(dateRange.oldest);
+    const daysDiff = Math.ceil(
+      (newestDate - oldestDate) / (1000 * 60 * 60 * 24)
+    );
+
+    text += `\n## Date Range\n\n`;
+    text += `| Boundary | Date |\n`;
+    text += `|----------|------|\n`;
+    text += `| Newest | ${newestDate.toLocaleString('en-AU')} |\n`;
+    text += `| Oldest | ${oldestDate.toLocaleString('en-AU')} |\n`;
+    text += `| Span | ${daysDiff} days |\n`;
+
+    meta.dateRange = dateRange;
+    meta.spanDays = daysDiff;
+  }
+
+  text += `\n## Recommendations\n\n`;
+
+  if (totalItems > 1000) {
+    text += `- **Large folder**: Use \`list-emails-delta\` for incremental sync\n`;
+    text += `- **Use date filters**: \`receivedAfter\` and \`receivedBefore\` to narrow scope\n`;
+  } else if (totalItems > 100) {
+    text += `- **Medium folder**: Consider using \`list-emails-delta\` for efficient updates\n`;
+  } else {
+    text += `- **Small folder**: \`list-emails\` with default pagination is efficient\n`;
+  }
+
+  if (unreadItems > 50) {
+    text += `- **Many unread**: Use \`unreadOnly: true\` filter to reduce results\n`;
+  }
+
+  return { text, meta };
+}
+
+module.exports = handleGetFolderStats;

package/index.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * Outlook Assistant Server - Main entry point
+ *
+ * A Model Context Protocol server that provides access to
+ * Microsoft Outlook through the Microsoft Graph API.
+ */
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const {
+  StdioServerTransport,
+} = require('@modelcontextprotocol/sdk/server/stdio.js');
+const config = require('./config');
+
+// Import module tools
+const { authTools } = require('./auth');
+const { calendarTools } = require('./calendar');
+const { emailTools } = require('./email');
+const { folderTools } = require('./folder');
+const { rulesTools } = require('./rules');
+const { contactsTools } = require('./contacts');
+const { categoriesTools } = require('./categories');
+const { settingsTools } = require('./settings');
+const { advancedTools } = require('./advanced');
+
+// Log startup information
+console.error(`STARTING ${config.SERVER_NAME.toUpperCase()} MCP SERVER`);
+console.error(`Test mode is ${config.USE_TEST_MODE ? 'enabled' : 'disabled'}`);
+
+// Combine all tools
+const TOOLS = [
+  ...authTools,
+  ...calendarTools,
+  ...emailTools,
+  ...folderTools,
+  ...rulesTools,
+  ...contactsTools,
+  ...categoriesTools,
+  ...settingsTools,
+  ...advancedTools,
+];
+
+// Create server with tools capabilities
+const server = new Server(
+  { name: config.SERVER_NAME, version: config.SERVER_VERSION },
+  {
+    capabilities: {
+      tools: TOOLS.reduce((acc, tool) => {
+        acc[tool.name] = {};
+        return acc;
+      }, {}),
+    },
+  }
+);
+
+// Handle all requests
+server.fallbackRequestHandler = async (request) => {
+  try {
+    const { method, params, id } = request;
+    console.error(`REQUEST: ${method} [${id}]`);
+
+    // Initialize handler
+    if (method === 'initialize') {
+      console.error(`INITIALIZE REQUEST: ID [${id}]`);
+      return {
+        protocolVersion: '2024-11-05',
+        capabilities: {
+          tools: TOOLS.reduce((acc, tool) => {
+            acc[tool.name] = {};
+            return acc;
+          }, {}),
+        },
+        serverInfo: {
+          name: config.SERVER_NAME,
+          version: config.SERVER_VERSION,
+        },
+      };
+    }
+
+    // Tools list handler
+    if (method === 'tools/list') {
+      console.error(`TOOLS LIST REQUEST: ID [${id}]`);
+      console.error(`TOOLS COUNT: ${TOOLS.length}`);
+      console.error(`TOOLS NAMES: ${TOOLS.map((t) => t.name).join(', ')}`);
+
+      return {
+        tools: TOOLS.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+          ...(tool.annotations && { annotations: tool.annotations }),
+        })),
+      };
+    }
+
+    // Required empty responses for other capabilities
+    if (method === 'resources/list') return { resources: [] };
+    if (method === 'prompts/list') return { prompts: [] };
+
+    // Tool call handler
+    if (method === 'tools/call') {
+      try {
+        const { name, arguments: args = {} } = params || {};
+
+        console.error(`TOOL CALL: ${name}`);
+
+        // Find the tool handler
+        const tool = TOOLS.find((t) => t.name === name);
+
+        if (tool && tool.handler) {
+          return await tool.handler(args);
+        }
+
+        // Tool not found
+        return {
+          error: {
+            code: -32601,
+            message: `Tool not found: ${name}`,
+          },
+        };
+      } catch (error) {
+        console.error(`Error in tools/call:`, error);
+        return {
+          error: {
+            code: -32603,
+            message: `Error processing tool call: ${error.message}`,
+          },
+        };
+      }
+    }
+
+    // For any other method, return method not found
+    return {
+      error: {
+        code: -32601,
+        message: `Method not found: ${method}`,
+      },
+    };
+  } catch (error) {
+    console.error(`Error in fallbackRequestHandler:`, error);
+    return {
+      error: {
+        code: -32603,
+        message: `Error processing request: ${error.message}`,
+      },
+    };
+  }
+};
+
+// Make the script executable
+process.on('SIGTERM', () => {
+  console.error('SIGTERM received but staying alive');
+});
+
+// Start the server
+const transport = new StdioServerTransport();
+server
+  .connect(transport)
+  .then(() => console.error(`${config.SERVER_NAME} connected and listening`))
+  .catch((error) => {
+    console.error(`Connection error: ${error.message}`);
+    process.exit(1);
+  });

package/llms.txt

@@ -0,0 +1,76 @@
+# Outlook Assistant Server
+
+> Give Claude full access to your Outlook email, calendar, and contacts through the Microsoft Graph API.
+
+Built by [Little Bear Apps](https://littlebearapps.com).
+
+## Key Information
+
+- **Package**: `@littlebearapps/outlook-assistant` on npm
+- **Install**: `npm install -g @littlebearapps/outlook-assistant` or `npx @littlebearapps/outlook-assistant`
+- **License**: MIT
+- **Node.js**: >= 18.0.0
+- **Authentication**: OAuth 2.0 with Microsoft Graph API (requires Azure app registration)
+- **Tools**: 20 consolidated tools across 9 modules (reduced from 55 for optimal AI performance)
+
+## Why Outlook Assistant?
+
+- Read, search, send, and export emails directly from Claude instead of switching apps
+- 6 email tools covering search, conversations, attachments, and bulk export
+- Manage calendar events, contacts, rules, categories, and mailbox settings in one place
+- Export to multiple formats: MIME/EML, MBOX, Markdown, JSON, HTML
+
+## Key Differentiators
+
+- **Progressive search**: Automatically falls back through 4 search strategies when Microsoft's `$search` API is unavailable (personal accounts) — most Graph API wrappers fail silently
+- **Email forensics**: Built-in header analysis for DKIM, SPF, DMARC authentication, delivery chains, and spam scores — useful for phishing investigation and compliance
+- **Delta sync**: Incremental inbox monitoring — returns only new, modified, and deleted emails since last check, with tokens for continuous polling
+- **Batch operations**: Flag, move, export, or categorise multiple emails in a single tool call; search-driven export for batch archiving without collecting IDs
+- **Compound automation**: Rules + categories + folders + Focused Inbox for complete inbox management in one conversation
+
+## Safety & Token Efficiency
+
+- **MCP safety annotations** on all 20 tools — AI clients auto-approve reads and prompt for destructive operations
+- **Send-email protections**: dry-run preview, session rate limiting, recipient allowlist
+- **Token-optimised**: 20 tools instead of 55 saves ~11,000 tokens per turn (~64% reduction), improving AI accuracy and context efficiency
+- These safeguards reduce risk but are not foolproof — always review actions before approving
+
+## Quick Start
+
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "npx",
+      "args": ["@littlebearapps/outlook-assistant"],
+      "env": {
+        "OUTLOOK_CLIENT_ID": "your-application-client-id",
+        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
+      }
+    }
+  }
+}
+```
+
+Requires an Azure app registration with Microsoft Graph delegated permissions. See README for full setup.
+
+## Tool Categories
+
+- **Authentication (1 tool)**: `auth` — OAuth flow, status, about
+- **Email (6 tools)**: `search-emails`, `read-email`, `send-email`, `update-email`, `attachments`, `export`
+- **Calendar (3 tools)**: `list-events`, `create-event`, `manage-event`
+- **Contacts (2 tools)**: `manage-contact`, `search-people`
+- **Folders (1 tool)**: `folders` — list, create, move, stats
+- **Rules (1 tool)**: `manage-rules` — list, create, reorder
+- **Categories (3 tools)**: `manage-category`, `apply-category`, `manage-focused-inbox`
+- **Settings (1 tool)**: `mailbox-settings` — get, set auto-replies, set working hours
+- **Advanced (2 tools)**: `access-shared-mailbox`, `find-meeting-rooms`
+
+## Documentation
+
+- [README](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/README.md): Full documentation including setup, Azure configuration, and usage
+- [Tools Reference](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/quickrefs/tools-reference.md): All 20 tools with parameters and safety annotations
+- [CLAUDE.md](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CLAUDE.md): Quick reference for development
+- [CONTRIBUTING](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CONTRIBUTING.md): Contribution guidelines
+- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history
+- [SECURITY](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/SECURITY.md): Security policy, token handling, and MCP safety controls