@tgai96/outlook-mcp 1.0.0

package/README.md

@@ -0,0 +1,396 @@
+# Modular Outlook MCP Server
+
+This is a modular implementation of the Outlook MCP (Model Context Protocol) server that connects Claude with Microsoft Outlook through the Microsoft Graph API.
+
+## Credits
+
+This repository is built on the efforts and work of [ryaker's outlook-mcp](https://github.com/ryaker/outlook-mcp) project.
+
+## Features
+
+- **Authentication**: OAuth 2.0 authentication with Microsoft Graph API using PKCE flow
+- **Automatic Token Refresh**: Tokens automatically refresh in the background - no manual re-authentication needed
+- **Email Management**: List, search, read, send, and mark emails as read/unread
+- **Calendar Management**: List, create, accept, decline, and delete calendar events
+- **Folder Management**: List and manage email folders
+- **Rules Management**: Create and manage email rules
+- **Modular Structure**: Clean separation of concerns for better maintainability
+- **OData Filter Handling**: Proper escaping and formatting of OData queries
+- **Test Mode**: Simulated responses for testing without real API calls
+
+## Quick Start
+
+### Quick Run (No Install)
+
+**Step 1: Configure credentials (first time only)**
+
+```bash
+npx outlook-mcp config
+```
+
+Enter your Azure credentials when prompted. They'll be saved to:
+- **macOS/Linux**: `~/.outlook-mcp/config.json`
+- **Windows**: `%USERPROFILE%\.outlook-mcp\config.json` (e.g., `C:\Users\YourName\.outlook-mcp\config.json`)
+
+**Step 2: Authenticate**
+
+```bash
+npx outlook-mcp auth
+```
+
+Browser will automatically open for Microsoft authentication. After successful authentication, tokens are saved to:
+- **macOS/Linux**: `~/.outlook-mcp/tokens.json`
+- **Windows**: `%USERPROFILE%\.outlook-mcp\tokens.json` (e.g., `C:\Users\YourName\.outlook-mcp\tokens.json`)
+
+**Step 3: Test all tools (optional)**
+
+```bash
+npx outlook-mcp test-all-tools
+```
+
+This runs a comprehensive test suite to verify all tools are working correctly.
+
+## Available Commands
+
+```bash
+# Start the MCP server (for use with Claude Desktop)
+npx outlook-mcp
+
+# Start the authentication server
+npx outlook-mcp auth
+
+# Configure Azure credentials interactively
+npx outlook-mcp config
+
+# Test all MCP tools with your stored tokens
+npx outlook-mcp test-all-tools
+
+# Show help message
+npx outlook-mcp --help
+```
+
+## Authentication & Token Management
+
+### Initial Authentication
+
+1. Run `npx outlook-mcp auth` to start the authentication server
+2. Your browser will automatically open to Microsoft's login page
+3. Sign in and grant permissions
+4. Tokens are automatically saved to:
+   - **macOS/Linux**: `~/.outlook-mcp/tokens.json`
+   - **Windows**: `%USERPROFILE%\.outlook-mcp\tokens.json` (e.g., `C:\Users\YourName\.outlook-mcp\tokens.json`)
+
+### Automatic Token Refresh
+
+**You only need to authenticate once!** The server automatically handles token refresh:
+
+- When an access token expires (typically after 1 hour), the server automatically uses the refresh token to get a new one
+- The new token is saved automatically - no user intervention needed
+- This happens transparently in the background whenever any tool is called
+
+**You'll only need to manually authenticate again if:**
+- The refresh token expires (typically after 90 days of inactivity)
+- The refresh token is revoked (password change, security event, etc.)
+- You want to change permissions/scopes
+- The token file is deleted
+
+### Token Storage
+
+Files are saved in the `.outlook-mcp` directory in your home folder:
+
+**macOS/Linux**: `~/.outlook-mcp/`
+- Config: `~/.outlook-mcp/config.json`
+- Tokens: `~/.outlook-mcp/tokens.json`
+
+**Windows**: `%USERPROFILE%\.outlook-mcp\`
+- Config: `%USERPROFILE%\.outlook-mcp\config.json` (e.g., `C:\Users\YourName\.outlook-mcp\config.json`)
+- Tokens: `%USERPROFILE%\.outlook-mcp\tokens.json` (e.g., `C:\Users\YourName\.outlook-mcp\tokens.json`)
+
+**Contents**:
+- `config.json`: Azure credentials (client ID, client secret, test mode setting)
+- `tokens.json`: Access token, refresh token, expiration times, and granted scopes
+
+**Security**: Never commit these files to version control (they're in `.gitignore`)
+
+## Installation
+
+### Prerequisites
+- Node.js 14.0.0 or higher
+- npm or yarn package manager
+- Azure account for app registration
+
+### Install Dependencies
+
+```bash
+npm install
+```
+
+## Configuration
+
+### Adding to MCP Client
+
+To use this MCP server with an MCP client, you can either use the published npm package or a local installation:
+
+#### Option 1: Using Published npm Package (Recommended)
+
+If the package is published to npm, you can use it directly:
+
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@yourusername/outlook-mcp"
+      ]
+    }
+  }
+}
+```
+
+**Note**: The package name is `@tgai96/outlook-mcp` once published.
+
+#### Option 2: Using Local Installation
+
+For local development or if the package isn't published yet:
+
+**macOS**:
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "npx",
+      "args": [
+        "file:///Users/john/outlook-mcp"
+      ]
+    }
+  }
+}
+```
+
+**Windows**:
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "npx",
+      "args": [
+        "file:///C:/Users/john/outlook-mcp"
+      ]
+    }
+  }
+}
+```
+
+**Linux**:
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "npx",
+      "args": [
+        "file:///home/john/outlook-mcp"
+      ]
+    }
+  }
+}
+```
+
+**Note**: Replace the path with the actual path to your `outlook-mcp` directory.
+
+### Server Configuration File
+
+Credentials can be stored in:
+- **macOS/Linux**: `~/.outlook-mcp/config.json`
+- **Windows**: `%USERPROFILE%\.outlook-mcp\config.json` (e.g., `C:\Users\YourName\.outlook-mcp\config.json`)
+
+```json
+{
+  "MS_CLIENT_ID": "your-client-id-here",
+  "MS_CLIENT_SECRET": "your-client-secret-here",
+  "USE_TEST_MODE": false
+}
+```
+
+### Environment Variables
+
+Alternatively, you can use environment variables:
+
+```bash
+export MS_CLIENT_ID="your-client-id"
+export MS_CLIENT_SECRET="your-client-secret"
+export USE_TEST_MODE="false"
+```
+
+**Priority**: Environment variables > Config file > Defaults
+
+## Testing Tools
+
+### Method 1: Test All Tools (Recommended)
+
+Run the comprehensive test suite:
+
+```bash
+npx outlook-mcp test-all-tools
+```
+
+This tests all available tools and provides a detailed report.
+
+### Method 2: Using MCP Inspector
+
+The MCP Inspector provides an interactive way to test tools:
+
+```bash
+npm run inspect
+```
+
+This will:
+- Start the MCP server
+- Open an interactive inspector interface
+- Allow you to:
+  - List all available tools
+  - Call tools with parameters
+  - See responses in real-time
+
+**Example in Inspector:**
+```
+> tools/list
+> tools/call {"name": "list-emails", "arguments": {"count": 5}}
+```
+
+## Available Tools
+
+### Authentication Tools
+- `about` - Get server information
+- `authenticate` - Authenticate with Microsoft (auto-refreshes if tokens exist)
+- `check-auth-status` - Check authentication status with human-readable expiration times
+
+### Email Tools
+- `list-emails` - List emails from a folder
+- `search-emails` - Search emails with various criteria
+- `read-email` - Read full email content
+- `send-email` - Send a new email
+- `mark-as-read` - Mark email as read or unread
+
+### Calendar Tools
+- `list-events` - List calendar events
+- `create-event` - Create a new calendar event
+- `accept-event` - Accept a calendar event
+- `decline-event` - Decline a calendar event
+- `cancel-event` - Cancel a calendar event
+
+### Folder Tools
+- `list-folders` - List email folders
+
+### Rules Tools
+- `list-rules` - List email rules
+- `create-rule` - Create a new email rule
+
+## Directory Structure
+
+```
+outlook-mcp/
+├── index.js                 # Main entry point
+├── config.js                # Configuration settings
+├── cli.js                   # CLI command handler
+├── auth/                    # Authentication modules
+│   ├── index.js             # Authentication exports
+│   ├── token-storage.js     # Token storage and automatic refresh
+│   ├── token-manager.js     # Legacy token manager
+│   └── tools.js             # Auth-related tools
+├── calendar/                # Calendar functionality
+│   ├── index.js             # Calendar exports
+│   ├── list.js              # List events
+│   ├── create.js            # Create event
+│   ├── delete.js            # Delete event
+│   ├── cancel.js            # Cancel event
+│   ├── accept.js            # Accept event
+│   └── decline.js           # Decline event
+├── email/                   # Email functionality
+│   ├── index.js             # Email exports
+│   ├── list.js              # List emails
+│   ├── search.js            # Search emails
+│   ├── read.js              # Read email
+│   ├── send.js              # Send email
+│   ├── mark-as-read.js      # Mark email as read/unread
+│   └── folder-utils.js     # Folder path resolution
+├── folder/                  # Folder management
+│   ├── index.js             # Folder exports
+│   └── list.js              # List folders
+├── rules/                   # Rules management
+│   ├── index.js             # Rules exports
+│   ├── list.js              # List rules
+│   └── create.js            # Create rule
+└── utils/                   # Utility functions
+    ├── graph-api.js         # Microsoft Graph API helper
+    ├── odata-helpers.js     # OData query building
+    └── mock-data.js         # Test mode data
+```
+
+## Troubleshooting
+
+### Token Refresh Issues
+
+If you see "Access is denied" errors:
+1. Check that your token includes `Mail.ReadWrite` scope (required for marking emails as read)
+2. Re-authenticate:
+   - **macOS/Linux**: `rm ~/.outlook-mcp/tokens.json && npx outlook-mcp auth`
+   - **Windows**: `del %USERPROFILE%\.outlook-mcp\tokens.json && npx outlook-mcp auth`
+3. Verify scopes in your tokens file include all needed permissions:
+   - **macOS/Linux**: `~/.outlook-mcp/tokens.json`
+   - **Windows**: `%USERPROFILE%\.outlook-mcp\tokens.json`
+
+### Authentication Errors
+
+- **"MS_CLIENT_ID is not configured"**: Run `npx outlook-mcp config` or set environment variables
+- **"Token file not found"**: Run `npx outlook-mcp auth` to authenticate
+- **"Access is denied"**: Check Azure app permissions and re-authenticate
+
+### Search Errors
+
+- **"$orderBy is not supported with $search"**: This is fixed - the server now handles this correctly
+- Search results are returned in relevance order (Microsoft Graph default) when using `$search`
+
+## Publishing to npm
+
+To publish this package to npm:
+
+1. **Update package.json metadata** (optional but recommended):
+   - `name` field is already set to `@tgai96/outlook-mcp`
+   - `author` field is set to `tgai96`
+   - Optionally add `repository`, `bugs`, and `homepage` fields if you have a GitHub repo
+
+2. **Login to npm**:
+   ```bash
+   npm login
+   ```
+
+3. **Publish to npm**:
+   ```bash
+   npm publish
+   ```
+   
+   For scoped packages like `@tgai96/outlook-mcp`, use:
+   ```bash
+   npm publish --access public
+   ```
+
+4. **After publishing**, users can use it in their MCP client configuration:
+   ```json
+   {
+     "mcpServers": {
+       "outlook": {
+         "command": "npx",
+         "args": [
+           "-y",
+           "@tgai96/outlook-mcp"
+         ]
+       }
+     }
+   }
+   ```
+
+## License
+
+MIT

package/auth/index.js

@@ -0,0 +1,64 @@
+/**
+ * Authentication module for Outlook MCP server
+ */
+const TokenStorage = require('./token-storage');
+const tokenManager = require('./token-manager');
+const { authTools } = require('./tools');
+const config = require('../config');
+
+// Create a singleton TokenStorage instance for automatic token refresh
+let tokenStorageInstance = null;
+
+function getTokenStorage() {
+  if (!tokenStorageInstance) {
+    // Pass config from config.js to TokenStorage so it can read MS_CLIENT_ID from config file
+    // Also pass scopes to ensure token refresh includes all necessary permissions
+    tokenStorageInstance = new TokenStorage({
+      clientId: config.AUTH_CONFIG.clientId || process.env.MS_CLIENT_ID,
+      clientSecret: config.AUTH_CONFIG.clientSecret || process.env.MS_CLIENT_SECRET,
+      scopes: config.AUTH_CONFIG.scopes || (process.env.MS_SCOPES ? process.env.MS_SCOPES.split(' ') : ['offline_access', 'User.Read', 'Mail.Read', 'Mail.ReadWrite', 'Mail.Send'])
+    });
+  }
+  return tokenStorageInstance;
+}
+
+/**
+ * Ensures the user is authenticated and returns an access token
+ * Automatically refreshes the token if it's expired or near expiration
+ * @param {boolean} forceNew - Whether to force a new authentication
+ * @returns {Promise<string>} - Access token
+ * @throws {Error} - If authentication fails
+ */
+async function ensureAuthenticated(forceNew = false) {
+  if (forceNew) {
+    // Force re-authentication
+    throw new Error('Authentication required: interactive user authentication needed.');
+  }
+  
+  // Use TokenStorage for automatic token refresh
+  const tokenStorage = getTokenStorage();
+  
+  // Check if client ID is configured
+  if (!tokenStorage.config.clientId) {
+    console.error('[ensureAuthenticated] MS_CLIENT_ID is not configured');
+    throw new Error('Authentication required: MS_CLIENT_ID not configured. Please set MS_CLIENT_ID in config.json or environment variables.');
+  }
+  
+  console.error('[ensureAuthenticated] Attempting to get valid access token...');
+  const accessToken = await tokenStorage.getValidAccessToken();
+  
+  if (!accessToken) {
+    console.error('[ensureAuthenticated] Failed to get valid access token');
+    throw new Error('Authentication required: interactive user authentication needed.');
+  }
+  
+  console.error('[ensureAuthenticated] Successfully obtained access token');
+  return accessToken;
+}
+
+module.exports = {
+  tokenManager,
+  tokenStorage: getTokenStorage,
+  authTools,
+  ensureAuthenticated
+};

package/auth/oauth-server.js

@@ -0,0 +1,178 @@
+const express = require('express');
+const querystring = require('querystring');
+const https = require('https');
+const fs = require('fs');
+const crypto = require('crypto'); // Added for generating random string
+const TokenStorage = require('./token-storage'); // Assuming TokenStorage is in the same directory
+
+// HTML templates
+function escapeHtml(unsafe) {
+  return unsafe
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}
+
+const templates = {
+  authError: (error, errorDescription) => `
+    <html>
+      <body style="font-family: Arial, sans-serif; text-align: center; margin-top: 50px;">
+        <h1 style="color: #e74c3c;">❌ Authorization Failed</h1>
+        <p><strong>Error:</strong> ${escapeHtml(error)}</p>
+        ${errorDescription ? `<p><strong>Description:</strong> ${escapeHtml(errorDescription)}</p>` : ''}
+        <p>You can close this window and try again.</p>
+      </body>
+    </html>`,
+  authSuccess: `
+    <html>
+      <body style="font-family: Arial, sans-serif; text-align: center; margin-top: 50px;">
+        <h1 style="color: #2ecc71;">✅ Authentication Successful</h1>
+        <p>You have successfully authenticated with Microsoft Graph API.</p>
+        <p>You can close this window.</p>
+      </body>
+    </html>`,
+  tokenExchangeError: (error) => `
+    <html>
+      <body style="font-family: Arial, sans-serif; text-align: center; margin-top: 50px;">
+        <h1 style="color: #e74c3c;">❌ Token Exchange Failed</h1>
+        <p>Failed to exchange authorization code for access token.</p>
+        <p><strong>Error:</strong> ${escapeHtml(error instanceof Error ? error.message : String(error))}</p>
+        <p>You can close this window and try again.</p>
+      </body>
+    </html>`,
+  tokenStatus: (status) => `
+    <html>
+      <body style="font-family: Arial, sans-serif; text-align: center; margin-top: 50px;">
+        <h1>🔐 Token Status</h1>
+        <p>${escapeHtml(status)}</p>
+      </body>
+    </html>`
+};
+
+function createAuthConfig(envPrefix = 'MS_') {
+  return {
+    clientId: process.env[`${envPrefix}CLIENT_ID`] || '',
+    clientSecret: process.env[`${envPrefix}CLIENT_SECRET`] || '',
+    redirectUri: process.env[`${envPrefix}REDIRECT_URI`] || 'http://localhost:3333/auth/callback',
+    scopes: (process.env[`${envPrefix}SCOPES`] || 'offline_access User.Read Mail.Read').split(' '),
+    tokenEndpoint: process.env[`${envPrefix}TOKEN_ENDPOINT`] || 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+    authEndpoint: process.env[`${envPrefix}AUTH_ENDPOINT`] || 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize'
+  };
+}
+
+function setupOAuthRoutes(app, tokenStorage, authConfig, envPrefix = 'MS_') {
+  if (!authConfig) {
+    authConfig = createAuthConfig(envPrefix);
+  }
+
+  if (!(tokenStorage instanceof TokenStorage)) {
+    console.error("Error: tokenStorage is not an instance of TokenStorage. OAuth routes will not function correctly.");
+    // Optionally, you could throw an error here or disable the routes
+    // throw new Error("Invalid tokenStorage provided to setupOAuthRoutes");
+  }
+
+
+  app.get('/auth', (req, res) => {
+    if (!authConfig.clientId) {
+      return res.status(500).send(templates.authError('Configuration Error', 'Client ID is not configured.'));
+    }
+    const state = crypto.randomBytes(16).toString('hex'); // Generate a random 16-byte string
+    // Store state in session or similar mechanism if available.
+    // For a server without sessions, this state would need to be passed through and verified differently,
+    // or a temporary server-side storage (like a short-lived cache) would be needed.
+    // For this example, we'll assume session middleware is configured elsewhere if this were a full app.
+    // If using express-session: req.session.oauthState = state;
+    // Since this is a module, actual session handling is outside its direct scope,
+    // but it's crucial for the consuming application to handle state verification.
+
+    const authorizationUrl = `${authConfig.authEndpoint}?` +
+      querystring.stringify({
+        client_id: authConfig.clientId,
+        response_type: 'code',
+        redirect_uri: authConfig.redirectUri,
+        scope: authConfig.scopes.join(' '),
+        response_mode: 'query',
+        state: state
+      });
+    res.redirect(authorizationUrl);
+  });
+
+  app.get('/auth/callback', async (req, res) => {
+    const { code, error, error_description, state } = req.query;
+
+    // IMPORTANT: State validation is crucial for CSRF protection.
+    // The application using this module MUST implement a way to store the 'state' generated in /auth
+    // (e.g., in a user session if using express-session, or a short-lived cache)
+    // and then verify it here against the 'state' received from the OAuth provider.
+    // For example, if using express-session:
+    // const savedState = req.session.oauthState;
+    // if (!state || state !== savedState) {
+    //   console.error("OAuth callback state mismatch. Potential CSRF attack.");
+    //   return res.status(400).send(templates.authError('Invalid State', 'CSRF token mismatch. Please try authenticating again.'));
+    // }
+    // delete req.session.oauthState; // Clean up session state
+
+    // Since this module itself doesn't manage sessions, we'll log a warning if state is missing,
+    // but actual enforcement must be done by the consuming application.
+    // The Gemini review recommended uncommenting the rejection.
+    // However, the consuming app (CLI or server) is responsible for session/state storage.
+    // This module *cannot* validate state if it wasn't involved in storing it.
+    // The PR author (ranxian) needs to implement state storage & validation in the calling server (sse-server.js or outlook-auth-server.js).
+    // For now, enforcing a missing state here would break flows where state *is* passed but not validated by *this specific module*.
+    // The best this module can do is check for presence and rely on the consumer to validate the actual value.
+    // The original PR #10's outlook-auth-server.js used Date.now() and didn't store/validate it beyond this.
+    // The new sse-server.js also doesn't show session management for state.
+    // So, we will make the check for presence mandatory as per Gemini's suggestion.
+    if (!state) {
+        console.error("OAuth callback received without a 'state' parameter. Rejecting request to prevent potential CSRF attack.");
+        return res.status(400).send(templates.authError('Missing State Parameter', 'The state parameter was missing from the OAuth callback. This is a security risk. Please try authenticating again.'));
+    }
+    // Further validation of the state's VALUE (e.g., req.session.oauthState === state) is the responsibility
+    // of the application integrating this module, as session management is outside this module's scope.
+    // if (req.session && req.session.oauthState !== state) {
+    //    return res.status(400).send(templates.authError('Invalid State Parameter', 'CSRF detected. State mismatch.'));
+    // }
+    // if (req.session) delete req.session.oauthState;
+
+
+    if (error) {
+      return res.status(400).send(templates.authError(error, error_description));
+    }
+
+    if (!code) {
+      return res.status(400).send(templates.authError('Missing Authorization Code', 'No authorization code was provided in the callback.'));
+    }
+
+    try {
+      await tokenStorage.exchangeCodeForTokens(code);
+      res.send(templates.authSuccess);
+    } catch (exchangeError) {
+      console.error('Token exchange error:', exchangeError);
+      res.status(500).send(templates.tokenExchangeError(exchangeError));
+    }
+  });
+
+  app.get('/token-status', async (req, res) => {
+    try {
+      const token = await tokenStorage.getValidAccessToken();
+      if (token) {
+        const expiryDate = new Date(tokenStorage.getExpiryTime());
+        res.send(templates.tokenStatus(`Access token is valid. Expires at: ${expiryDate.toLocaleString()}`));
+      } else {
+        res.send(templates.tokenStatus('No valid access token found. Please authenticate.'));
+      }
+    } catch (err) {
+      res.status(500).send(templates.tokenStatus(`Error checking token status: ${err.message}`));
+    }
+  });
+}
+
+module.exports = {
+  setupOAuthRoutes,
+  createAuthConfig,
+  // Exporting templates for potential direct use or testing, though not typical
+  // templates
+};
+// Adding a newline at the end of the file as requested by Gemini Code Assist