@tgai96/outlook-mcp 1.0.0

package/folder/index.js

@@ -0,0 +1,78 @@
+/**
+ * Folder management module for Outlook MCP server
+ */
+const handleListFolders = require('./list');
+const handleCreateFolder = require('./create');
+const handleMoveEmails = require('./move');
+
+// Folder management tool definitions
+const folderTools = [
+  {
+    name: "list-folders",
+    description: "Lists mail folders in your Outlook account",
+    inputSchema: {
+      type: "object",
+      properties: {
+        includeItemCounts: {
+          type: "boolean",
+          description: "Include counts of total and unread items"
+        },
+        includeChildren: {
+          type: "boolean",
+          description: "Include child folders in hierarchy"
+        }
+      },
+      required: []
+    },
+    handler: handleListFolders
+  },
+  {
+    name: "create-folder",
+    description: "Creates a new mail folder",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Name of the folder to create"
+        },
+        parentFolder: {
+          type: "string",
+          description: "Optional parent folder name (default is root)"
+        }
+      },
+      required: ["name"]
+    },
+    handler: handleCreateFolder
+  },
+  {
+    name: "move-emails",
+    description: "Moves emails from one folder to another",
+    inputSchema: {
+      type: "object",
+      properties: {
+        emailIds: {
+          type: "string",
+          description: "Comma-separated list of email IDs to move"
+        },
+        targetFolder: {
+          type: "string",
+          description: "Name of the folder to move emails to"
+        },
+        sourceFolder: {
+          type: "string",
+          description: "Optional name of the source folder (default is inbox)"
+        }
+      },
+      required: ["emailIds", "targetFolder"]
+    },
+    handler: handleMoveEmails
+  }
+];
+
+module.exports = {
+  folderTools,
+  handleListFolders,
+  handleCreateFolder,
+  handleMoveEmails
+};

package/folder/list.js

@@ -0,0 +1,264 @@
+/**
+ * List folders functionality
+ */
+const { callGraphAPI } = require('../utils/graph-api');
+const { ensureAuthenticated } = require('../auth');
+
+/**
+ * List folders handler
+ * @param {object} args - Tool arguments
+ * @returns {object} - MCP response
+ */
+async function handleListFolders(args) {
+  const includeItemCounts = args.includeItemCounts === true;
+  const includeChildren = args.includeChildren === true;
+  
+  try {
+    // Get access token
+    const accessToken = await ensureAuthenticated();
+    
+    // Get all mail folders
+    const folders = await getAllFoldersHierarchy(accessToken, includeItemCounts);
+    
+    // If including children, format as hierarchy
+    if (includeChildren) {
+      return {
+        content: [{ 
+          type: "text", 
+          text: formatFolderHierarchy(folders, includeItemCounts)
+        }]
+      };
+    } else {
+      // Otherwise, format as flat list
+      return {
+        content: [{ 
+          type: "text", 
+          text: formatFolderList(folders, includeItemCounts)
+        }]
+      };
+    }
+  } 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 folders: ${error.message}`
+      }]
+    };
+  }
+}
+
+/**
+ * Get all mail folders with hierarchy information
+ * @param {string} accessToken - Access token
+ * @param {boolean} includeItemCounts - Include item counts in response
+ * @returns {Promise<Array>} - Array of folder objects with hierarchy
+ */
+async function getAllFoldersHierarchy(accessToken, includeItemCounts) {
+  try {
+    // Determine select fields based on whether to include counts
+    const selectFields = includeItemCounts
+      ? 'id,displayName,parentFolderId,childFolderCount,totalItemCount,unreadItemCount'
+      : 'id,displayName,parentFolderId,childFolderCount';
+    
+    // Get all mail folders
+    const response = await callGraphAPI(
+      accessToken,
+      'GET',
+      'me/mailFolders',
+      null,
+      { 
+        $top: 100,
+        $select: selectFields
+      }
+    );
+    
+    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: selectFields }
+        );
+        
+        // Add parent folder info to each child
+        const childFolders = childResponse.value || [];
+        childFolders.forEach(child => {
+          child.parentFolder = folder.displayName;
+        });
+        
+        return childFolders;
+      } catch (error) {
+        console.error(`Error getting child folders for "${folder.displayName}": ${error.message}`);
+        return [];
+      }
+    });
+    
+    const childFolders = await Promise.all(childFolderPromises);
+    const allChildFolders = childFolders.flat();
+    
+    // Add top-level flag to parent folders
+    const topLevelFolders = response.value.map(folder => ({
+      ...folder,
+      isTopLevel: true
+    }));
+    
+    // Combine all folders
+    return [...topLevelFolders, ...allChildFolders];
+  } catch (error) {
+    console.error(`Error getting all folders: ${error.message}`);
+    throw error;
+  }
+}
+
+/**
+ * Format folders as a flat list
+ * @param {Array} folders - Array of folder objects
+ * @param {boolean} includeItemCounts - Whether to include item counts
+ * @returns {string} - Formatted list
+ */
+function formatFolderList(folders, includeItemCounts) {
+  if (!folders || folders.length === 0) {
+    return "No folders found.";
+  }
+  
+  // Sort folders alphabetically, with well-known folders first
+  const wellKnownFolderNames = ['Inbox', 'Drafts', 'Sent Items', 'Deleted Items', 'Junk Email', 'Archive'];
+  
+  const sortedFolders = [...folders].sort((a, b) => {
+    // Well-known folders come first
+    const aIsWellKnown = wellKnownFolderNames.includes(a.displayName);
+    const bIsWellKnown = wellKnownFolderNames.includes(b.displayName);
+    
+    if (aIsWellKnown && !bIsWellKnown) return -1;
+    if (!aIsWellKnown && bIsWellKnown) return 1;
+    
+    if (aIsWellKnown && bIsWellKnown) {
+      // Sort well-known folders by their index in the array
+      return wellKnownFolderNames.indexOf(a.displayName) - wellKnownFolderNames.indexOf(b.displayName);
+    }
+    
+    // Sort other folders alphabetically
+    return a.displayName.localeCompare(b.displayName);
+  });
+  
+  // Format each folder
+  const folderLines = sortedFolders.map(folder => {
+    let folderInfo = folder.displayName;
+    
+    // Add parent folder info if available
+    if (folder.parentFolder) {
+      folderInfo += ` (in ${folder.parentFolder})`;
+    }
+    
+    // Add item counts if requested
+    if (includeItemCounts) {
+      const unreadCount = folder.unreadItemCount || 0;
+      const totalCount = folder.totalItemCount || 0;
+      folderInfo += ` - ${totalCount} items`;
+      
+      if (unreadCount > 0) {
+        folderInfo += ` (${unreadCount} unread)`;
+      }
+    }
+    
+    return folderInfo;
+  });
+  
+  return `Found ${folders.length} folders:\n\n${folderLines.join('\n')}`;
+}
+
+/**
+ * Format folders as a hierarchical tree
+ * @param {Array} folders - Array of folder objects
+ * @param {boolean} includeItemCounts - Whether to include item counts
+ * @returns {string} - Formatted hierarchy
+ */
+function formatFolderHierarchy(folders, includeItemCounts) {
+  if (!folders || folders.length === 0) {
+    return "No folders found.";
+  }
+  
+  // Build folder hierarchy
+  const folderMap = new Map();
+  const rootFolders = [];
+  
+  // First pass: create map of all folders
+  folders.forEach(folder => {
+    folderMap.set(folder.id, {
+      ...folder,
+      children: []
+    });
+    
+    if (folder.isTopLevel) {
+      rootFolders.push(folder.id);
+    }
+  });
+  
+  // Second pass: build hierarchy
+  folders.forEach(folder => {
+    if (!folder.isTopLevel && folder.parentFolderId) {
+      const parent = folderMap.get(folder.parentFolderId);
+      if (parent) {
+        parent.children.push(folder.id);
+      } else {
+        // Fallback for orphaned folders
+        rootFolders.push(folder.id);
+      }
+    }
+  });
+  
+  // Format hierarchy recursively
+  function formatSubtree(folderId, level = 0) {
+    const folder = folderMap.get(folderId);
+    if (!folder) return '';
+    
+    const indent = '  '.repeat(level);
+    let line = `${indent}${folder.displayName}`;
+    
+    // Add item counts if requested
+    if (includeItemCounts) {
+      const unreadCount = folder.unreadItemCount || 0;
+      const totalCount = folder.totalItemCount || 0;
+      line += ` - ${totalCount} items`;
+      
+      if (unreadCount > 0) {
+        line += ` (${unreadCount} unread)`;
+      }
+    }
+    
+    // Add children
+    const childLines = folder.children
+      .map(childId => formatSubtree(childId, level + 1))
+      .filter(line => line.length > 0)
+      .join('\n');
+    
+    return childLines.length > 0 ? `${line}\n${childLines}` : line;
+  }
+  
+  // Format all root folders
+  const formattedHierarchy = rootFolders
+    .map(folderId => formatSubtree(folderId))
+    .join('\n');
+  
+  return `Folder Hierarchy:\n\n${formattedHierarchy}`;
+}
+
+module.exports = handleListFolders;

package/folder/move.js

@@ -0,0 +1,163 @@
+/**
+ * Move emails functionality
+ */
+const { callGraphAPI } = require('../utils/graph-api');
+const { ensureAuthenticated } = require('../auth');
+const { getFolderIdByName } = require('../email/folder-utils');
+
+/**
+ * Move emails handler
+ * @param {object} args - Tool arguments
+ * @returns {object} - MCP response
+ */
+async function handleMoveEmails(args) {
+  const emailIds = args.emailIds || '';
+  const targetFolder = args.targetFolder || '';
+  const sourceFolder = args.sourceFolder || '';
+  
+  if (!emailIds) {
+    return {
+      content: [{ 
+        type: "text", 
+        text: "Email IDs are required. Please provide a comma-separated list of email IDs to move."
+      }]
+    };
+  }
+  
+  if (!targetFolder) {
+    return {
+      content: [{ 
+        type: "text", 
+        text: "Target folder name is required."
+      }]
+    };
+  }
+  
+  try {
+    // Get access token
+    const accessToken = await ensureAuthenticated();
+    
+    // Parse email IDs
+    const ids = emailIds.split(',').map(id => id.trim()).filter(id => id);
+    
+    if (ids.length === 0) {
+      return {
+        content: [{ 
+          type: "text", 
+          text: "No valid email IDs provided."
+        }]
+      };
+    }
+    
+    // Move emails
+    const result = await moveEmailsToFolder(accessToken, ids, targetFolder, sourceFolder);
+    
+    return {
+      content: [{ 
+        type: "text", 
+        text: result.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 moving emails: ${error.message}`
+      }]
+    };
+  }
+}
+
+/**
+ * Move emails to a folder
+ * @param {string} accessToken - Access token
+ * @param {Array<string>} emailIds - Array of email IDs to move
+ * @param {string} targetFolderName - Name of the target folder
+ * @param {string} sourceFolderName - Name of the source folder (optional)
+ * @returns {Promise<object>} - Result object with status and message
+ */
+async function moveEmailsToFolder(accessToken, emailIds, targetFolderName, sourceFolderName) {
+  try {
+    // Get the target folder ID
+    const targetFolderId = await getFolderIdByName(accessToken, targetFolderName);
+    if (!targetFolderId) {
+      return {
+        success: false,
+        message: `Target folder "${targetFolderName}" not found. Please specify a valid folder name.`
+      };
+    }
+    
+    // Track successful and failed moves
+    const results = {
+      successful: [],
+      failed: []
+    };
+    
+    // Process each email one by one to handle errors independently
+    for (const emailId of emailIds) {
+      try {
+        // Move the email
+        await callGraphAPI(
+          accessToken,
+          'POST',
+          `me/messages/${emailId}/move`,
+          {
+            destinationId: targetFolderId
+          }
+        );
+        
+        results.successful.push(emailId);
+      } catch (error) {
+        console.error(`Error moving email ${emailId}: ${error.message}`);
+        results.failed.push({
+          id: emailId,
+          error: error.message
+        });
+      }
+    }
+    
+    // Generate result message
+    let message = '';
+    
+    if (results.successful.length > 0) {
+      message += `Successfully moved ${results.successful.length} email(s) to "${targetFolderName}".`;
+    }
+    
+    if (results.failed.length > 0) {
+      if (message) message += '\n\n';
+      message += `Failed to move ${results.failed.length} email(s). Errors:`;
+      
+      // Show first few errors with details
+      const maxErrors = Math.min(results.failed.length, 3);
+      for (let i = 0; i < maxErrors; i++) {
+        const failure = results.failed[i];
+        message += `\n- Email ${i+1}: ${failure.error}`;
+      }
+      
+      // If there are more errors, just mention the count
+      if (results.failed.length > maxErrors) {
+        message += `\n...and ${results.failed.length - maxErrors} more.`;
+      }
+    }
+    
+    return {
+      success: results.successful.length > 0,
+      message,
+      results
+    };
+  } catch (error) {
+    console.error(`Error in moveEmailsToFolder: ${error.message}`);
+    throw error;
+  }
+}
+
+module.exports = handleMoveEmails;

package/index.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * Outlook MCP 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');
+
+// 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
+  // Future modules: contactsTools, etc.
+];
+
+// 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
+        }))
+      };
+    }
+    
+    // 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/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@tgai96/outlook-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Claude to access Outlook data via Microsoft Graph API",
+  "main": "index.js",
+  "bin": {
+    "outlook-mcp": "./cli.js"
+  },
+  "files": [
+    "index.js",
+    "cli.js",
+    "config.js",
+    "auth/",
+    "calendar/",
+    "email/",
+    "folder/",
+    "rules/",
+    "utils/",
+    ".env.example",
+    "claude-config-sample.json"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node index.js",
+    "test-all-tools": "node test-mcp-tools.js",
+    "test": "jest"
+  },
+  "keywords": [
+    "claude",
+    "outlook",
+    "mcp",
+    "microsoft-graph",
+    "email",
+    "calendar",
+    "model-context-protocol"
+  ],
+  "author": "tgai96",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.1.0",
+    "dotenv": "^16.5.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/inspector": "^0.10.2",
+    "jest": "^29.7.0",
+    "supertest": "^7.0.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}