outlook-cli 1.2.0

package/email/folder-utils.js

@@ -0,0 +1,171 @@
+/**
+ * Email folder utilities
+ */
+const { callGraphAPI } = require('../utils/graph-api');
+
+/**
+ * Cache of folder information to reduce API calls
+ * Format: { userId: { folderName: { id, path } } }
+ */
+const folderCache = {};
+
+/**
+ * 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 'me/messages';
+  }
+  
+  // Handle well-known folder names
+  const wellKnownFolders = {
+    'inbox': 'me/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'
+  };
+  
+  // Check if it's a well-known folder (case-insensitive)
+  const lowerFolderName = folderName.toLowerCase();
+  if (wellKnownFolders[lowerFolderName]) {
+    console.error(`Using well-known folder path for "${folderName}"`);
+    return wellKnownFolders[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 'me/messages';
+  } catch (error) {
+    console.error(`Error resolving folder "${folderName}": ${error.message}`);
+    return 'me/messages';
+  }
+}
+
+/**
+ * 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 = {
+  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,89 @@
+/**
+ * List emails functionality
+ */
+const config = require('../config');
+const { callGraphAPI } = require('../utils/graph-api');
+const { ensureAuthenticated } = require('../auth');
+
+/**
+ * List emails handler
+ * @param {object} args - Tool arguments
+ * @returns {object} - MCP response
+ */
+async function handleListEmails(args) {
+  const folder = args.folder || "inbox";
+  const count = Math.min(args.count || 10, config.MAX_RESULT_COUNT);
+  
+  try {
+    // Get access token
+    const accessToken = await ensureAuthenticated();
+    
+    // Build API endpoint
+    let endpoint = 'me/messages';
+    if (folder.toLowerCase() !== 'inbox') {
+      // Get folder ID first if not inbox
+      const folderResponse = await callGraphAPI(
+        accessToken, 
+        'GET', 
+        `me/mailFolders?$filter=displayName eq '${folder}'`
+      );
+      
+      if (folderResponse.value && folderResponse.value.length > 0) {
+        endpoint = `me/mailFolders/${folderResponse.value[0].id}/messages`;
+      }
+    }
+    
+    // Add query parameters
+    const queryParams = {
+      $top: count,
+      $orderby: 'receivedDateTime desc',
+      $select: config.EMAIL_SELECT_FIELDS
+    };
+    
+    // Make API call
+    const response = await callGraphAPI(accessToken, 'GET', endpoint, null, queryParams);
+    
+    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;

package/email/read.js

@@ -0,0 +1,128 @@
+/**
+ * Read email functionality
+ */
+const config = require('../config');
+const { callGraphAPI } = require('../utils/graph-api');
+const { ensureAuthenticated } = require('../auth');
+
+/**
+ * Read email handler
+ * @param {object} args - Tool arguments
+ * @returns {object} - MCP response
+ */
+async function handleReadEmail(args) {
+  const emailId = args.id;
+  
+  if (!emailId) {
+    return {
+      content: [{ 
+        type: "text", 
+        text: "Email ID is required."
+      }]
+    };
+  }
+  
+  try {
+    // Get access token
+    const accessToken = await ensureAuthenticated();
+    
+    // Make API call to get email details
+    const endpoint = `me/messages/${encodeURIComponent(emailId)}`;
+    const queryParams = {
+      $select: config.EMAIL_DETAIL_FIELDS
+    };
+    
+    try {
+      const email = await callGraphAPI(accessToken, 'GET', endpoint, null, queryParams);
+      
+      if (!email) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Email with ID ${emailId} not found.`
+            }
+          ]
+        };
+      }
+      
+      // Format sender, recipients, etc.
+      const sender = email.from ? `${email.from.emailAddress.name} (${email.from.emailAddress.address})` : 'Unknown';
+      const to = email.toRecipients ? email.toRecipients.map(r => `${r.emailAddress.name} (${r.emailAddress.address})`).join(", ") : 'None';
+      const cc = email.ccRecipients && email.ccRecipients.length > 0 ? email.ccRecipients.map(r => `${r.emailAddress.name} (${r.emailAddress.address})`).join(", ") : 'None';
+      const bcc = email.bccRecipients && email.bccRecipients.length > 0 ? email.bccRecipients.map(r => `${r.emailAddress.name} (${r.emailAddress.address})`).join(", ") : 'None';
+      const date = new Date(email.receivedDateTime).toLocaleString();
+      
+      // Extract body content
+      let body = '';
+      if (email.body) {
+        body = email.body.contentType === 'html' ? 
+          // Simple HTML-to-text conversion for HTML bodies
+          email.body.content.replace(/<[^>]*>/g, '') : 
+          email.body.content;
+      } else {
+        body = email.bodyPreview || 'No content';
+      }
+      
+      // Format the email
+      const formattedEmail = `From: ${sender}
+To: ${to}
+${cc !== 'None' ? `CC: ${cc}\n` : ''}${bcc !== 'None' ? `BCC: ${bcc}\n` : ''}Subject: ${email.subject}
+Date: ${date}
+Importance: ${email.importance || 'normal'}
+Has Attachments: ${email.hasAttachments ? 'Yes' : 'No'}
+
+${body}`;
+      
+      return {
+        content: [
+          {
+            type: "text",
+            text: formattedEmail
+          }
+        ]
+      };
+    } catch (error) {
+      console.error(`Error reading email: ${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 {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Failed to read email: ${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 = handleReadEmail;