@littlebearapps/outlook-assistant 3.3.1 → 3.4.1

package/README.md

@@ -2,14 +2,20 @@
   <img src="docs/assets/outlook-assistant-logo-full.svg" height="200" alt="Outlook Assistant" />
 </p>
 
+<h1 align="center">Outlook Assistant</h1>
+
 <p align="center">
-  <strong>Let your AI assistant read, search, send, and manage your Outlook email, calendar, and contacts — all from the conversation.</strong>
+  <strong>MCP server for Outlook email, calendar, and contacts — let your AI assistant manage your inbox directly from the conversation.</strong>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@littlebearapps/outlook-assistant"><img src="https://img.shields.io/npm/v/@littlebearapps/outlook-assistant" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/@littlebearapps/outlook-assistant"><img src="https://img.shields.io/npm/dm/@littlebearapps/outlook-assistant" alt="npm downloads" /></a>
+  <a href="https://github.com/littlebearapps/outlook-assistant/stargazers"><img src="https://img.shields.io/github/stars/littlebearapps/outlook-assistant" alt="GitHub stars" /></a>
+  <a href="https://github.com/littlebearapps/outlook-assistant/commits/main"><img src="https://img.shields.io/github/last-commit/littlebearapps/outlook-assistant" alt="Last commit" /></a>
   <a href="https://github.com/littlebearapps/outlook-assistant/actions/workflows/ci.yml"><img src="https://github.com/littlebearapps/outlook-assistant/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/littlebearapps/outlook-assistant/actions/workflows/codeql.yml"><img src="https://github.com/littlebearapps/outlook-assistant/actions/workflows/codeql.yml/badge.svg" alt="CodeQL" /></a>
+  <a href="https://github.com/littlebearapps/outlook-assistant/issues"><img src="https://img.shields.io/github/issues/littlebearapps/outlook-assistant" alt="Open issues" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="Node.js" /></a>
 </p>
@@ -79,6 +85,7 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 | `markdown` | `.md` | Pasting into documents, feeding into AI workflows |
 | `json` | `.json` | Data analysis, pipeline processing, compliance reporting |
 | `html` | `.html` | Visual archival with formatting intact |
+| `csv` | `.csv` | Spreadsheet import, bulk metadata analysis, compliance audits |
 
 Export individual emails, search results, or entire conversation threads — use `target=messages` with a search query to batch-export without manually collecting IDs.
 
@@ -150,7 +157,58 @@ You need a Microsoft Azure app registration to authenticate. See the **[Azure Se
 
 ### 3. Configure Your MCP Client
 
-Add to your MCP client config. For Claude Desktop (`claude_desktop_config.json`):
+Add to your MCP client config:
+
+<details>
+<summary><strong>Claude Desktop</strong> (<code>claude_desktop_config.json</code>)</summary>
+
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "npx",
+      "args": ["@littlebearapps/outlook-assistant"],
+      "env": {
+        "OUTLOOK_CLIENT_ID": "your-application-client-id",
+        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Claude Code</strong> (CLI)</summary>
+
+```bash
+claude mcp add outlook -- npx @littlebearapps/outlook-assistant
+```
+
+Then set environment variables in your `.env` or shell.
+</details>
+
+<details>
+<summary><strong>Cursor</strong> (<code>.cursor/mcp.json</code>)</summary>
+
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "npx",
+      "args": ["@littlebearapps/outlook-assistant"],
+      "env": {
+        "OUTLOOK_CLIENT_ID": "your-application-client-id",
+        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Windsurf</strong> (<code>~/.codeium/windsurf/mcp_config.json</code>)</summary>
 
 ```json
 {
@@ -166,6 +224,7 @@ Add to your MCP client config. For Claude Desktop (`claude_desktop_config.json`)
   }
 }
 ```
+</details>
 
 ### 4. Authenticate
 
@@ -258,24 +317,9 @@ USE_TEST_MODE=false
 
 ### MCP Client Configuration
 
-Add to your MCP client config (example for Claude Desktop):
-
-```json
-{
-  "mcpServers": {
-    "outlook": {
-      "command": "npx",
-      "args": ["@littlebearapps/outlook-assistant"],
-      "env": {
-        "OUTLOOK_CLIENT_ID": "your-application-client-id",
-        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
-      }
-    }
-  }
-}
-```
+See [Quick Start — Configure Your MCP Client](#3-configure-your-mcp-client) above for Claude Desktop, Claude Code, Cursor, and Windsurf configs.
 
-Or if installed from source:
+If installed from source, use `node` instead of `npx`:
 
 ```json
 {
@@ -427,6 +471,10 @@ For security concerns, please see our [Security Policy](SECURITY.md). Do not ope
 
 See [CHANGELOG.md](CHANGELOG.md) for version history.
 
+## Listed On
+
+<a href="https://glama.ai/mcp/servers/littlebearapps/outlook-assistant"><img width="190" height="100" src="https://glama.ai/mcp/servers/littlebearapps/outlook-assistant/badge" alt="Outlook Assistant on Glama" /></a>
+
 ## About
 
 Built and maintained by [Little Bear Apps](https://littlebearapps.com). Outlook Assistant is open source under the [MIT License](LICENSE).

package/advanced/index.js

@@ -11,6 +11,7 @@
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { FIELD_PRESETS } = require('../utils/field-presets');
+const { DEFAULT_TIMEZONE } = require('../config');
 
 /**
  * Format an email for display (simplified)
@@ -224,16 +225,32 @@ async function handleSetMessageFlag(args) {
     };
 
     if (dueDateTime) {
+      // Graph API expects { dateTime, timeZone } envelope without trailing Z
+      // When timeZone is specified, the dateTime value is interpreted in that zone
+      const dueDt = dueDateTime.replace(/Z$/i, '');
       flag.dueDateTime = {
-        dateTime: new Date(dueDateTime).toISOString(),
-        timeZone: 'UTC',
+        dateTime: dueDt,
+        timeZone: DEFAULT_TIMEZONE,
       };
-    }
 
-    if (startDateTime) {
+      // Graph API requires startDateTime when dueDateTime is set
+      // Default to start of the same day if not explicitly provided
+      if (startDateTime) {
+        flag.startDateTime = {
+          dateTime: startDateTime.replace(/Z$/i, ''),
+          timeZone: DEFAULT_TIMEZONE,
+        };
+      } else {
+        const startOfDay = dueDt.split('T')[0] + 'T09:00:00';
+        flag.startDateTime = {
+          dateTime: startOfDay,
+          timeZone: DEFAULT_TIMEZONE,
+        };
+      }
+    } else if (startDateTime) {
       flag.startDateTime = {
-        dateTime: new Date(startDateTime).toISOString(),
-        timeZone: 'UTC',
+        dateTime: startDateTime.replace(/Z$/i, ''),
+        timeZone: DEFAULT_TIMEZONE,
       };
     }
 

package/config.js

@@ -26,7 +26,7 @@ if (!homeDir) {
 module.exports = {
   // Server information
   SERVER_NAME: 'outlook-assistant',
-  SERVER_VERSION: '3.3.0',
+  SERVER_VERSION: require('./package.json').version,
 
   // Test mode setting
   USE_TEST_MODE: process.env.USE_TEST_MODE === 'true',

package/email/conversations.js

@@ -14,6 +14,7 @@ const { ensureAuthenticated } = require('../auth');
 const { getEmailFields } = require('../utils/field-presets');
 const {
   formatEmailContent,
+  formatEmailsAsCSV,
   VERBOSITY,
 } = require('../utils/response-formatter');
 
@@ -329,7 +330,7 @@ async function handleExportConversation(args) {
     };
   }
 
-  const validFormats = ['eml', 'mbox', 'markdown', 'json', 'html'];
+  const validFormats = ['eml', 'mbox', 'markdown', 'json', 'html', 'csv'];
   if (!validFormats.includes(format)) {
     return {
       content: [
@@ -602,6 +603,16 @@ async function handleExportConversation(args) {
         exportedFiles.push(htmlPath);
         break;
       }
+
+      case 'csv': {
+        // Export as CSV
+        const csvPath = path.join(resolvedDir, `${filenameBase}.csv`);
+        const csvContent = formatEmailsAsCSV(messages);
+        fs.writeFileSync(csvPath, csvContent, 'utf8');
+        exportStats.bytes = Buffer.byteLength(csvContent, 'utf8');
+        exportedFiles.push(csvPath);
+        break;
+      }
     }
 
     // Format result

package/email/export.js

@@ -11,6 +11,7 @@ const { callGraphAPI, callGraphAPIRaw } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const {
   formatEmailContent,
+  formatEmailsAsCSV,
   VERBOSITY,
 } = require('../utils/response-formatter');
 const { getEmailFields } = require('../utils/field-presets');
@@ -21,6 +22,7 @@ const EXPORT_FORMATS = {
   EML: 'eml', // Alias for MIME
   MARKDOWN: 'markdown',
   JSON: 'json',
+  CSV: 'csv',
 };
 
 /**
@@ -111,12 +113,15 @@ async function handleExportEmail(args) {
     } else if (format === EXPORT_FORMATS.JSON) {
       // JSON export - full email object
       content = JSON.stringify(email, null, 2);
+    } else if (format === EXPORT_FORMATS.CSV) {
+      // CSV export - email metadata
+      content = formatEmailsAsCSV(email);
     } else {
       return {
         content: [
           {
             type: 'text',
-            text: `Unknown format: ${format}. Supported: mime, eml, markdown, json`,
+            text: `Unknown format: ${format}. Supported: ${Object.values(EXPORT_FORMATS).join(', ')}`,
           },
         ],
       };
@@ -254,6 +259,68 @@ async function handleBatchExportEmails(args) {
       console.error(`Batch export limited to ${maxBatch} emails`);
     }
 
+    // CSV batch export: aggregate all emails into a single CSV file
+    if (format === EXPORT_FORMATS.CSV) {
+      const selectFields = getEmailFields('export');
+      const emails = [];
+      const failed = [];
+
+      for (const emailId of idsToExport) {
+        try {
+          const email = await callGraphAPI(
+            accessToken,
+            'GET',
+            `me/messages/${emailId}`,
+            null,
+            { $select: selectFields }
+          );
+          emails.push(email);
+        } catch (error) {
+          failed.push({ emailId, error: error.message });
+        }
+      }
+
+      const csvContent = formatEmailsAsCSV(emails);
+      const csvPath = path.join(
+        outputDir,
+        `batch_export_${new Date().toISOString().slice(0, 10)}.csv`
+      );
+      fs.writeFileSync(csvPath, csvContent, 'utf8');
+      const totalBytes = Buffer.byteLength(csvContent, 'utf8');
+
+      let resultText = `## Batch Export Complete\n\n`;
+      resultText += `| Metric | Value |\n`;
+      resultText += `|--------|-------|\n`;
+      resultText += `| Total | ${idsToExport.length} |\n`;
+      resultText += `| Successful | ${emails.length} |\n`;
+      resultText += `| Failed | ${failed.length} |\n`;
+      resultText += `| Output File | \`${csvPath}\` |\n`;
+      resultText += `| Format | CSV |\n`;
+      resultText += `| Total Size | ${(totalBytes / 1024).toFixed(1)} KB |\n`;
+
+      if (failed.length > 0) {
+        resultText += `\n### Failed Exports\n\n`;
+        for (const f of failed.slice(0, 10)) {
+          resultText += `- ID \`${f.emailId}\`: ${f.error}\n`;
+        }
+        if (failed.length > 10) {
+          resultText += `- ... and ${failed.length - 10} more\n`;
+        }
+      }
+
+      return {
+        content: [{ type: 'text', text: resultText }],
+        _meta: {
+          outputDir,
+          format,
+          total: idsToExport.length,
+          successful: emails.length,
+          failed: failed.length,
+          totalBytes,
+        },
+      };
+    }
+
     // Export emails with concurrency limit (4 concurrent per Graph API limits)
     const results = await exportWithConcurrency(
       accessToken,
@@ -559,6 +626,8 @@ function getExtension(format) {
       return 'eml';
     case EXPORT_FORMATS.JSON:
       return 'json';
+    case EXPORT_FORMATS.CSV:
+      return 'csv';
     case EXPORT_FORMATS.MARKDOWN:
     default:
       return 'md';

package/email/folder-utils.js

@@ -10,15 +10,39 @@ const { callGraphAPI } = require('../utils/graph-api');
 const _folderCache = {};
 
 /**
- * Well-known folder names and their endpoints
+ * Well-known folder names and their endpoints.
+ * Includes Graph API well-known names (sentitems, deleteditems, junkemail),
+ * common display names (Sent Items, Deleted Items, Junk Email), and
+ * short aliases (sent, deleted, junk) for consistent resolution across tools.
  */
 const WELL_KNOWN_FOLDERS = {
+  // Inbox
   inbox: 'me/mailFolders/inbox/messages',
+
+  // Drafts
   drafts: 'me/mailFolders/drafts/messages',
+
+  // Sent Items - alias, Graph API name, display name
   sent: 'me/mailFolders/sentItems/messages',
+  sentitems: 'me/mailFolders/sentItems/messages',
+  'sent items': 'me/mailFolders/sentItems/messages',
+
+  // Deleted Items - alias, Graph API name, display name
   deleted: 'me/mailFolders/deletedItems/messages',
+  deleteditems: 'me/mailFolders/deletedItems/messages',
+  'deleted items': 'me/mailFolders/deletedItems/messages',
+
+  // Junk Email - alias, Graph API name, display name, common alias
   junk: 'me/mailFolders/junkemail/messages',
+  junkemail: 'me/mailFolders/junkemail/messages',
+  'junk email': 'me/mailFolders/junkemail/messages',
+  spam: 'me/mailFolders/junkemail/messages',
+
+  // Archive
   archive: 'me/mailFolders/archive/messages',
+
+  // Outbox
+  outbox: 'me/mailFolders/outbox/messages',
 };
 
 /**

package/email/index.js

@@ -434,9 +434,9 @@ const emailTools = [
         },
         format: {
           type: 'string',
-          enum: ['mime', 'eml', 'markdown', 'json', 'mbox', 'html'],
+          enum: ['mime', 'eml', 'markdown', 'json', 'mbox', 'html', 'csv'],
           description:
-            'Export format (target=message: mime/eml/markdown/json, target=conversation: eml/mbox/markdown/json/html)',
+            'Export format (target=message: mime/eml/markdown/json/csv, target=conversation: eml/mbox/markdown/json/html/csv)',
         },
         savePath: {
           type: 'string',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.3.1",
+  "version": "3.4.1",
   "mcpName": "io.github.littlebearapps/outlook-assistant",
   "description": "Outlook Assistant — MCP server with 20 tools for email, calendar, contacts, and settings via Microsoft Graph API",
   "main": "index.js",
@@ -17,7 +17,8 @@
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "prepare": "husky"
+    "prepare": "husky || true",
+    "version": "node -e \"const s=require('./server.json');const p=require('./package.json');s.version=p.version;s.packages[0].version=p.version;require('fs').writeFileSync('./server.json',JSON.stringify(s,null,2)+'\\n')\" && git add server.json"
   },
   "lint-staged": {
     "*.js": [

package/settings/index.js

@@ -129,7 +129,9 @@ async function handleGetMailboxSettings(args) {
         output.push(`**Locale**: ${settings.locale || 'Not set'}`);
         output.push(`**Display Name**: ${settings.displayName || 'Not set'}`);
       } else if (section === 'timeZone') {
-        output.push(`**Zone**: ${settings}`);
+        // Graph API returns { value: "timezone string" } for scalar properties
+        const tz = typeof settings === 'string' ? settings : settings.value;
+        output.push(`**Zone**: ${tz || 'Not set'}`);
       } else {
         // Fallback for unknown sections
         output.push('```json');

package/utils/response-formatter.js

@@ -283,6 +283,49 @@ function formatEmailContent(
   return output;
 }
 
+/**
+ * Formats one or more emails as a CSV string with a header row.
+ * Accepts a single email object or an array of email objects.
+ * Only exports metadata columns - no body content.
+ * @param {object|object[]} emails - Single email or array of emails from Graph API
+ * @returns {string} - CSV string with header row and one row per email
+ */
+function formatEmailsAsCSV(emails) {
+  const CSV_HEADERS = [
+    'id',
+    'subject',
+    'from',
+    'to',
+    'cc',
+    'receivedDateTime',
+    'isRead',
+    'importance',
+    'hasAttachments',
+  ];
+
+  const emailList = Array.isArray(emails) ? emails : [emails];
+
+  const rows = emailList.map((email) => {
+    const from = formatEmailAddress(email.from?.emailAddress);
+    const to = formatRecipients(email.toRecipients);
+    const cc = formatRecipients(email.ccRecipients);
+
+    return [
+      email.id || '',
+      email.subject || '',
+      from,
+      to,
+      cc,
+      email.receivedDateTime || '',
+      email.isRead != null ? String(email.isRead) : '',
+      email.importance || '',
+      email.hasAttachments != null ? String(email.hasAttachments) : '',
+    ].map(escapeCSV);
+  });
+
+  return [CSV_HEADERS.join(','), ...rows.map((r) => r.join(','))].join('\n');
+}
+
 /**
  * Formats email headers for legal/forensic use
  * @param {Array} headers - Array of header objects
@@ -435,6 +478,26 @@ function stripHtml(html) {
     .trim();
 }
 
+function escapeCSV(value) {
+  if (value === null || value === undefined) return '';
+  const str = String(value);
+  const needsQuoting =
+    str.includes(',') ||
+    str.includes('"') ||
+    str.includes('\n') ||
+    str.includes('\r');
+  const formulaChars = ['=', '+', '-', '@', '\t', '\r', '\n'];
+  const isFormula = formulaChars.some((ch) => str.startsWith(ch));
+
+  if (isFormula) {
+    return '"' + "'" + str.replace(/"/g, '""') + '"';
+  }
+  if (needsQuoting) {
+    return '"' + str.replace(/"/g, '""') + '"';
+  }
+  return str;
+}
+
 module.exports = {
   VERBOSITY,
   DEFAULT_LIMITS,
@@ -445,6 +508,7 @@ module.exports = {
   formatEmailList,
   formatEmailListAsTable,
   formatEmailContent,
+  formatEmailsAsCSV,
   formatEmailHeaders,
   createResponseMeta,
   wrapMcpResponse,
@@ -454,4 +518,5 @@ module.exports = {
   formatRecipients,
   truncateText,
   stripHtml,
+  escapeCSV,
 };