@tgai96/outlook-mcp 1.0.0

package/config.js

@@ -0,0 +1,108 @@
+/**
+ * Configuration for Outlook MCP Server
+ */
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+// Ensure we have a home directory path even if process.env.HOME is undefined
+const homeDir = process.env.HOME || process.env.USERPROFILE || os.homedir() || '/tmp';
+const configDir = path.join(homeDir, '.outlook-mcp');
+const configFilePath = path.join(configDir, 'config.json');
+
+/**
+ * Load configuration from file
+ * Priority: Environment variables > Config file > Defaults
+ */
+function loadConfig() {
+  let fileConfig = {};
+  
+  // Try to load from config file
+  try {
+    if (fs.existsSync(configFilePath)) {
+      const configData = fs.readFileSync(configFilePath, 'utf8');
+      fileConfig = JSON.parse(configData);
+    }
+  } catch (error) {
+    console.error(`Warning: Could not load config from ${configFilePath}:`, error.message);
+  }
+  
+  // Priority: env vars > file config > defaults
+  return {
+    // Test mode: env > file > default
+    USE_TEST_MODE: process.env.USE_TEST_MODE === 'true' || fileConfig.USE_TEST_MODE === true || fileConfig.USE_TEST_MODE === 'true',
+    
+    // Client ID: env > file > default
+    OUTLOOK_CLIENT_ID: process.env.OUTLOOK_CLIENT_ID || fileConfig.MS_CLIENT_ID || fileConfig.OUTLOOK_CLIENT_ID || '',
+    
+    // Client Secret: env > file > default
+    OUTLOOK_CLIENT_SECRET: process.env.OUTLOOK_CLIENT_SECRET || fileConfig.MS_CLIENT_SECRET || fileConfig.OUTLOOK_CLIENT_SECRET || '',
+    
+    // MS_CLIENT_ID for auth server: env > file > default
+    MS_CLIENT_ID: process.env.MS_CLIENT_ID || fileConfig.MS_CLIENT_ID || '',
+    
+    // MS_CLIENT_SECRET for auth server: env > file > default
+    MS_CLIENT_SECRET: process.env.MS_CLIENT_SECRET || fileConfig.MS_CLIENT_SECRET || '',
+  };
+}
+
+const loadedConfig = loadConfig();
+
+module.exports = {
+  // Server information
+  SERVER_NAME: "outlook-assistant",
+  SERVER_VERSION: "1.0.0",
+  
+  // Test mode setting
+  USE_TEST_MODE: loadedConfig.USE_TEST_MODE,
+  
+  // Authentication configuration
+  AUTH_CONFIG: {
+    clientId: loadedConfig.OUTLOOK_CLIENT_ID || loadedConfig.MS_CLIENT_ID || '',
+    clientSecret: loadedConfig.OUTLOOK_CLIENT_SECRET || loadedConfig.MS_CLIENT_SECRET || '',
+    redirectUri: 'http://localhost:3333/auth/callback',
+    scopes: ['Mail.Read', 'Mail.ReadWrite', 'Mail.Send', 'User.Read', 'Calendars.Read', 'Calendars.ReadWrite'],
+    tokenStorePath: path.join(homeDir, '.outlook-mcp', 'tokens.json'),
+    authServerUrl: 'http://localhost:3333',
+    configFilePath: configFilePath
+  },
+  
+  // Export config loading utilities
+  loadConfig: loadConfig,
+  saveConfig: function(config) {
+    try {
+      // Ensure directory exists
+      if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+      }
+      
+      // Save config file
+      fs.writeFileSync(configFilePath, JSON.stringify(config, null, 2), 'utf8');
+      return true;
+    } catch (error) {
+      console.error(`Error saving config to ${configFilePath}:`, error.message);
+      return false;
+    }
+  },
+  configFilePath: configFilePath,
+  
+  // Microsoft Graph API
+  GRAPH_API_ENDPOINT: 'https://graph.microsoft.com/v1.0/',
+  
+  // Calendar constants
+  CALENDAR_SELECT_FIELDS: 'id,subject,start,end,location,bodyPreview,isAllDay,recurrence,attendees',
+
+  // Email constants
+  EMAIL_SELECT_FIELDS: 'id,subject,from,toRecipients,ccRecipients,receivedDateTime,bodyPreview,hasAttachments,importance,isRead',
+  EMAIL_DETAIL_FIELDS: 'id,subject,from,toRecipients,ccRecipients,bccRecipients,receivedDateTime,bodyPreview,body,hasAttachments,importance,isRead,internetMessageHeaders',
+  
+  // Calendar constants
+  CALENDAR_SELECT_FIELDS: 'id,subject,bodyPreview,start,end,location,organizer,attendees,isAllDay,isCancelled',
+  
+  // Pagination
+  DEFAULT_PAGE_SIZE: 25,
+  MAX_RESULT_COUNT: 50,
+
+  // Timezone
+  DEFAULT_TIMEZONE: "Central European Standard Time",
+};

package/email/folder-utils.js

@@ -0,0 +1,175 @@
+/**
+ * Email folder utilities
+ */
+const { callGraphAPI } = require('../utils/graph-api');
+
+/**
+ * Cache of folder information to reduce API calls
+ * Format: { userId: { folderName: { id, path } } }
+ */
+const folderCache = {};
+
+/**
+ * Well-known folder names and their endpoints
+ */
+const WELL_KNOWN_FOLDERS = {
+  'inbox': 'me/mailFolders/inbox/messages',
+  'drafts': 'me/mailFolders/drafts/messages',
+  'sent': 'me/mailFolders/sentItems/messages',
+  'deleted': 'me/mailFolders/deletedItems/messages',
+  'junk': 'me/mailFolders/junkemail/messages',
+  'archive': 'me/mailFolders/archive/messages'
+};
+
+/**
+ * Resolve a folder name to its endpoint path
+ * @param {string} accessToken - Access token
+ * @param {string} folderName - Folder name to resolve
+ * @returns {Promise<string>} - Resolved endpoint path
+ */
+async function resolveFolderPath(accessToken, folderName) {
+
+  // Default to inbox if no folder specified
+  if (!folderName) {
+    return WELL_KNOWN_FOLDERS['inbox'];
+  }
+
+  // Check if it's a well-known folder (case-insensitive)
+  const lowerFolderName = folderName.toLowerCase();
+  if (WELL_KNOWN_FOLDERS[lowerFolderName]) {
+    console.error(`Using well-known folder path for "${folderName}"`);
+    return WELL_KNOWN_FOLDERS[lowerFolderName];
+  }
+
+  try {
+    // Try to find the folder by name
+    const folderId = await getFolderIdByName(accessToken, folderName);
+    if (folderId) {
+      const path = `me/mailFolders/${folderId}/messages`;
+      console.error(`Resolved folder "${folderName}" to path: ${path}`);
+      return path;
+    }
+
+    // If not found, fall back to inbox
+    console.error(`Couldn't find folder "${folderName}", falling back to inbox`);
+    return WELL_KNOWN_FOLDERS['inbox'];
+  } catch (error) {
+    console.error(`Error resolving folder "${folderName}": ${error.message}`);
+    return WELL_KNOWN_FOLDERS['inbox'];
+  }
+}
+
+/**
+ * Get the ID of a mail folder by its name
+ * @param {string} accessToken - Access token
+ * @param {string} folderName - Name of the folder to find
+ * @returns {Promise<string|null>} - Folder ID or null if not found
+ */
+async function getFolderIdByName(accessToken, folderName) {
+  try {
+    // First try with exact match filter
+    console.error(`Looking for folder with name "${folderName}"`);
+    const response = await callGraphAPI(
+      accessToken,
+      'GET',
+      'me/mailFolders',
+      null,
+      { $filter: `displayName eq '${folderName}'` }
+    );
+    
+    if (response.value && response.value.length > 0) {
+      console.error(`Found folder "${folderName}" with ID: ${response.value[0].id}`);
+      return response.value[0].id;
+    }
+    
+    // If exact match fails, try to get all folders and do a case-insensitive comparison
+    console.error(`No exact match found for "${folderName}", trying case-insensitive search`);
+    const allFoldersResponse = await callGraphAPI(
+      accessToken,
+      'GET',
+      'me/mailFolders',
+      null,
+      { $top: 100 }
+    );
+    
+    if (allFoldersResponse.value) {
+      const lowerFolderName = folderName.toLowerCase();
+      const matchingFolder = allFoldersResponse.value.find(
+        folder => folder.displayName.toLowerCase() === lowerFolderName
+      );
+      
+      if (matchingFolder) {
+        console.error(`Found case-insensitive match for "${folderName}" with ID: ${matchingFolder.id}`);
+        return matchingFolder.id;
+      }
+    }
+    
+    console.error(`No folder found matching "${folderName}"`);
+    return null;
+  } catch (error) {
+    console.error(`Error finding folder "${folderName}": ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Get all mail folders
+ * @param {string} accessToken - Access token
+ * @returns {Promise<Array>} - Array of folder objects
+ */
+async function getAllFolders(accessToken) {
+  try {
+    // Get top-level folders
+    const response = await callGraphAPI(
+      accessToken,
+      'GET',
+      'me/mailFolders',
+      null,
+      { 
+        $top: 100,
+        $select: 'id,displayName,parentFolderId,childFolderCount,totalItemCount,unreadItemCount'
+      }
+    );
+    
+    if (!response.value) {
+      return [];
+    }
+    
+    // Get child folders for folders with children
+    const foldersWithChildren = response.value.filter(f => f.childFolderCount > 0);
+    
+    const childFolderPromises = foldersWithChildren.map(async (folder) => {
+      try {
+        const childResponse = await callGraphAPI(
+          accessToken,
+          'GET',
+          `me/mailFolders/${folder.id}/childFolders`,
+          null,
+          { 
+            $select: 'id,displayName,parentFolderId,childFolderCount,totalItemCount,unreadItemCount'
+          }
+        );
+        
+        return childResponse.value || [];
+      } catch (error) {
+        console.error(`Error getting child folders for "${folder.displayName}": ${error.message}`);
+        return [];
+      }
+    });
+    
+    const childFolders = await Promise.all(childFolderPromises);
+    
+    // Combine top-level folders and all child folders
+    return [...response.value, ...childFolders.flat()];
+  } catch (error) {
+    console.error(`Error getting all folders: ${error.message}`);
+    return [];
+  }
+}
+
+module.exports = {
+  WELL_KNOWN_FOLDERS,
+  resolveFolderPath,
+  getFolderIdByName,
+  getAllFolders
+};

package/email/index.js

@@ -0,0 +1,157 @@
+/**
+ * Email module for Outlook MCP server
+ */
+const handleListEmails = require('./list');
+const handleSearchEmails = require('./search');
+const handleReadEmail = require('./read');
+const handleSendEmail = require('./send');
+const handleMarkAsRead = require('./mark-as-read');
+
+// Email tool definitions
+const emailTools = [
+  {
+    name: "list-emails",
+    description: "Lists recent emails from your inbox",
+    inputSchema: {
+      type: "object",
+      properties: {
+        folder: {
+          type: "string",
+          description: "Email folder to list (e.g., 'inbox', 'sent', 'drafts', default: 'inbox')"
+        },
+        count: {
+          type: "number",
+          description: "Number of emails to retrieve (default: 10, max: 50)"
+        }
+      },
+      required: []
+    },
+    handler: handleListEmails
+  },
+  {
+    name: "search-emails",
+    description: "Search for emails using various criteria",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Search query text to find in emails"
+        },
+        folder: {
+          type: "string",
+          description: "Email folder to search in (default: 'inbox')"
+        },
+        from: {
+          type: "string",
+          description: "Filter by sender email address or name"
+        },
+        to: {
+          type: "string",
+          description: "Filter by recipient email address or name"
+        },
+        subject: {
+          type: "string",
+          description: "Filter by email subject"
+        },
+        hasAttachments: {
+          type: "boolean",
+          description: "Filter to only emails with attachments"
+        },
+        unreadOnly: {
+          type: "boolean",
+          description: "Filter to only unread emails"
+        },
+        count: {
+          type: "number",
+          description: "Number of results to return (default: 10, max: 50)"
+        }
+      },
+      required: []
+    },
+    handler: handleSearchEmails
+  },
+  {
+    name: "read-email",
+    description: "Reads the content of a specific email",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "ID of the email to read"
+        }
+      },
+      required: ["id"]
+    },
+    handler: handleReadEmail
+  },
+  {
+    name: "send-email",
+    description: "Composes and sends a new email",
+    inputSchema: {
+      type: "object",
+      properties: {
+        to: {
+          type: "string",
+          description: "Comma-separated list of recipient email addresses"
+        },
+        cc: {
+          type: "string",
+          description: "Comma-separated list of CC recipient email addresses"
+        },
+        bcc: {
+          type: "string",
+          description: "Comma-separated list of BCC recipient email addresses"
+        },
+        subject: {
+          type: "string",
+          description: "Email subject"
+        },
+        body: {
+          type: "string",
+          description: "Email body content (can be plain text or HTML)"
+        },
+        importance: {
+          type: "string",
+          description: "Email importance (normal, high, low)",
+          enum: ["normal", "high", "low"]
+        },
+        saveToSentItems: {
+          type: "boolean",
+          description: "Whether to save the email to sent items"
+        }
+      },
+      required: ["to", "subject", "body"]
+    },
+    handler: handleSendEmail
+  },
+  {
+    name: "mark-as-read",
+    description: "Marks an email as read or unread",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "ID of the email to mark as read/unread"
+        },
+        isRead: {
+          type: "boolean",
+          description: "Whether to mark as read (true) or unread (false). Default: true"
+        }
+      },
+      required: ["id"]
+    },
+    handler: handleMarkAsRead
+  }
+];
+
+module.exports = {
+  emailTools,
+  handleListEmails,
+  handleSearchEmails,
+  handleReadEmail,
+  handleSendEmail,
+  handleMarkAsRead
+};

package/email/list.js

@@ -0,0 +1,78 @@
+/**
+ * List emails functionality
+ */
+const config = require('../config');
+const { callGraphAPI, callGraphAPIPaginated } = require('../utils/graph-api');
+const { ensureAuthenticated } = require('../auth');
+const { resolveFolderPath } = require('./folder-utils');
+
+/**
+ * List emails handler
+ * @param {object} args - Tool arguments
+ * @returns {object} - MCP response
+ */
+async function handleListEmails(args) {
+  const folder = args.folder || "inbox";
+  const requestedCount = args.count || 10;
+  
+  try {
+    // Get access token
+    const accessToken = await ensureAuthenticated();
+
+    // Resolve the folder path
+    const endpoint = await resolveFolderPath(accessToken, folder);
+    
+    // Add query parameters
+    const queryParams = {
+      $top: Math.min(50, requestedCount), // Use 50 per page for efficiency
+      $orderby: 'receivedDateTime desc',
+      $select: config.EMAIL_SELECT_FIELDS
+    };
+    
+    // Make API call with pagination support
+    const response = await callGraphAPIPaginated(accessToken, 'GET', endpoint, queryParams, requestedCount);
+    
+    if (!response.value || response.value.length === 0) {
+      return {
+        content: [{ 
+          type: "text", 
+          text: `No emails found in ${folder}.`
+        }]
+      };
+    }
+    
+    // Format results
+    const emailList = response.value.map((email, index) => {
+      const sender = email.from ? email.from.emailAddress : { name: 'Unknown', address: 'unknown' };
+      const date = new Date(email.receivedDateTime).toLocaleString();
+      const readStatus = email.isRead ? '' : '[UNREAD] ';
+      
+      return `${index + 1}. ${readStatus}${date} - From: ${sender.name} (${sender.address})\nSubject: ${email.subject}\nID: ${email.id}\n`;
+    }).join("\n");
+    
+    return {
+      content: [{ 
+        type: "text", 
+        text: `Found ${response.value.length} emails in ${folder}:\n\n${emailList}`
+      }]
+    };
+  } 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 listing emails: ${error.message}`
+      }]
+    };
+  }
+}
+
+module.exports = handleListEmails;

package/email/mark-as-read.js

@@ -0,0 +1,101 @@
+/**
+ * Mark email as read functionality
+ */
+const config = require('../config');
+const { callGraphAPI } = require('../utils/graph-api');
+const { ensureAuthenticated } = require('../auth');
+
+/**
+ * Mark email as read handler
+ * @param {object} args - Tool arguments
+ * @returns {object} - MCP response
+ */
+async function handleMarkAsRead(args) {
+  const emailId = args.id;
+  const isRead = args.isRead !== undefined ? args.isRead : true; // Default to true
+  
+  if (!emailId) {
+    return {
+      content: [{ 
+        type: "text", 
+        text: "Email ID is required."
+      }]
+    };
+  }
+  
+  try {
+    // Get access token
+    const accessToken = await ensureAuthenticated();
+    
+    // Make API call to update email read status
+    const endpoint = `me/messages/${encodeURIComponent(emailId)}`;
+    const updateData = {
+      isRead: isRead
+    };
+    
+    try {
+      const result = await callGraphAPI(accessToken, 'PATCH', endpoint, updateData);
+      
+      const status = isRead ? 'read' : 'unread';
+      
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Email successfully marked as ${status}.`
+          }
+        ]
+      };
+    } catch (error) {
+      console.error(`Error marking email as ${isRead ? 'read' : 'unread'}: ${error.message}`);
+      
+      // Improved error handling with more specific messages
+      if (error.message.includes("doesn't belong to the targeted mailbox")) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `The email ID seems invalid or doesn't belong to your mailbox. Please try with a different email ID.`
+            }
+          ]
+        };
+      } else if (error.message.includes("UNAUTHORIZED")) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Authentication failed. Please re-authenticate and try again."
+            }
+          ]
+        };
+      } else {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Failed to mark email as ${isRead ? 'read' : 'unread'}: ${error.message}`
+            }
+          ]
+        };
+      }
+    }
+  } 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 accessing email: ${error.message}`
+      }]
+    };
+  }
+}
+
+module.exports = handleMarkAsRead;