@littlebearapps/outlook-assistant 3.3.0 → 3.4.0

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>
@@ -18,19 +24,29 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 
 **Works with personal Outlook.com and work/school Microsoft 365 accounts.**
 
+<div align="center">
+  <br />
+  <a href="docs/demo/outlook-assistant-demo.mp4">
+    <img src="docs/demo/outlook-assistant-demo.gif" alt="Outlook Assistant Demo — searching emails, reading, and drafting a reply" width="720" style="border-radius: 12px; box-shadow: 0 8px 32px rgba(0,0,0,0.12);" />
+  </a>
+  <br />
+  <sub>Search inbox → read &amp; summarise → draft a reply — all from the conversation</sub>
+  <br /><br />
+</div>
+
 ### What you can do
 
-- **Search and read emails** — find messages by sender, subject, date, or keywords; read full threads with conversation grouping; batch flag, move, export, or categorise multiple emails at once
-- **Send emails with safety controls** — dry-run preview, session rate limiting, and recipient allowlist to prevent mistakes
-- **Manage your calendar** — view upcoming events, schedule meetings with attendees, decline or cancel invitations
-- **Export emails** — save to Markdown, EML, MBOX, JSON, or HTML for archiving, analysis, or migration; export search results or entire threads in one call
-- **Investigate email headers** — check DKIM, SPF, and DMARC authentication; trace delivery chains; analyse spam scores — useful for phishing investigation and compliance
-- **Organise your inbox** — create folders, set up inbox rules, colour-code with categories, manage Focused Inbox — all work together for complete inbox automation
-- **Track inbox changes** — delta sync detects new, modified, and deleted emails since your last check, with tokens for incremental polling
-- **Manage contacts** — search your contact book and organisational directory, create and update contact records
-- **Configure settings** — set out-of-office auto-replies, working hours, and time zone
-- **Access shared mailboxes** — read team inboxes and service accounts (Microsoft 365)
-- **Find meeting rooms** — search by building, floor, capacity, AV equipment, and wheelchair accessibility (Microsoft 365)
+- 📨 **Search and read emails** — find messages by sender, subject, date, or keywords; read full threads with conversation grouping; batch flag, move, export, or categorise multiple emails at once
+- 🛡️ **Send emails with safety controls** — dry-run preview, session rate limiting, and recipient allowlist to prevent mistakes
+- 📅 **Manage your calendar** — view upcoming events, schedule meetings with attendees, decline or cancel invitations
+- 📦 **Export emails** — save to Markdown, EML, MBOX, JSON, or HTML for archiving, analysis, or migration; export search results or entire threads in one call
+- 🔍 **Investigate email headers** — check DKIM, SPF, and DMARC authentication; trace delivery chains; analyse spam scores — useful for phishing investigation and compliance
+- 🗂️ **Organise your inbox** — create folders, set up inbox rules, colour-code with categories, manage Focused Inbox — all work together for complete inbox automation
+- 🔄 **Track inbox changes** — delta sync detects new, modified, and deleted emails since your last check, with tokens for incremental polling
+- 👥 **Manage contacts** — search your contact book and organisational directory, create and update contact records
+- ⚙️ **Configure settings** — set out-of-office auto-replies, working hours, and time zone
+- 📬 **Access shared mailboxes** — read team inboxes and service accounts (Microsoft 365)
+- 🏢 **Find meeting rooms** — search by building, floor, capacity, AV equipment, and wheelchair accessibility (Microsoft 365)
 
 ### Why Outlook Assistant?
 
@@ -69,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.
 
@@ -140,7 +157,10 @@ 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
 {
@@ -156,6 +176,55 @@ Add to your MCP client config. For Claude Desktop (`claude_desktop_config.json`)
   }
 }
 ```
+</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
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "npx",
+      "args": ["@littlebearapps/outlook-assistant"],
+      "env": {
+        "OUTLOOK_CLIENT_ID": "your-application-client-id",
+        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
+      }
+    }
+  }
+}
+```
+</details>
 
 ### 4. Authenticate
 
@@ -248,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
 {
@@ -417,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/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/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.0",
+  "version": "3.4.0",
   "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,7 @@
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "prepare": "husky"
+    "prepare": "husky || true"
   },
   "lint-staged": {
     "*.js": [

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,
 };