ms365-mcp-server 1.0.0 → 1.0.2

package/README.md

@@ -1,27 +1,25 @@
 # ✉️ Microsoft 365 MCP Server
 
-A powerful **Model Context Protocol (MCP) server** that enables seamless Microsoft 365 email integration through natural language interactions. Built for **Claude Desktop**, **LLMs**, and any MCP-compatible application.
-
-This project provides an **MCP (Model Context Protocol) server** that enables **Claude Desktop** to access your **Microsoft 365 email** seamlessly. It acts as a bridge between AI models and email services by exposing mailbox capabilities through a **secure, standardized interface**.
+A powerful **Model Context Protocol (MCP) server** that enables seamless Microsoft 365 email integration through natural language interactions. Built for **Claude Desktop**, **LLMs**, and any MCP-compatible application with **production-ready security**.
 
 ## ✨ Key Features
 
 - **Complete Microsoft 365 integration** with OAuth2 security via Azure MSAL
 - **Intuitive email management** - send, read, search, and organize emails
 - **Smart email search** with advanced filtering and criteria support
-- **Email organization** with read/unread marking and folder management
 - **File attachment support** - send and receive attachments seamlessly
-- **Multi-user support** for teams and shared environments
+- **Enhanced security** with simplified single-user authentication model
 - **Contact management** - retrieve and search your contact directory
-- **Secure authentication** with local token storage and automatic refresh
+- **Secure authentication** with OS keychain storage and automatic refresh
 - **Cross-platform compatibility** (macOS, Linux, Windows)
 
 ## 🛠️ Tools & Capabilities
 
-### 📧 Core Email Operations (11 tools)
+### 📧 Core Email Operations (12 tools)
 - **`send_email`** - Send emails with attachments, HTML/text content, CC/BCC
 - **`read_email`** - Read full email content including headers and attachments  
 - **`search_emails`** - Advanced search with filtering and date ranges
+- **`search_emails_to_me`** - Find emails addressed to YOU (both TO and CC fields)
 - **`list_emails`** - List emails in inbox, sent, or custom folders
 - **`get_attachment`** - Download and retrieve email attachments
 - **`mark_email`** - Mark emails as read or unread
@@ -31,84 +29,24 @@ This project provides an **MCP (Model Context Protocol) server** that enables **
 - **`get_contacts`** - Retrieve contact list from Microsoft 365
 - **`search_contacts`** - Search contacts by name or email address
 
-### 🔐 Authentication Tools (10 tools)
-- **`quick_authenticate`** - One-time authentication with auto browser launch (single-user mode)
-- **`get_auth_link`** - Get clickable authentication link for manual control (single-user mode)
-- **`device_code_login`** - Device code authentication flow (no browser auto-open)
-- **`get_device_code`** - Get device code info for manual authentication
+### 🔐 Authentication Tools (6 tools)
+- **`authenticate_with_device_code`** - Complete authentication in MCP (RECOMMENDED)
+- **`device_code_login`** - Start device code authentication flow
+- **`check_pending_auth`** - Check for pending device code authentication
 - **`verify_authentication`** - Check current authentication status
-- **`list_authenticated_accounts`** - Show all authenticated accounts
-- **`get_storage_info`** - Display credential storage method information
-- **`logout`** - Clear authentication tokens for current user
-- **`authenticate_user`** - Start authentication flow for new users (multi-user mode)  
-- **`get_my_session_info`** - View your own session information (multi-user mode)
-
-**Total: 21 tools** (11 email operations + 10 authentication tools)
-
-## 🌟 Key Feature Highlights
-
-### ✅ Supported Email Features
-
-* **Email Sending**
-  * Send plain text or HTML emails
-  * Add attachments and send in bulk
-  * Support for CC, BCC, and reply-to addresses
-  * Email importance levels (low, normal, high)
-
-* **Email Receiving & Querying**
-  * List folders and retrieve email metadata
-  * Advanced queries: filter by sender, subject, date, or addressed recipient (To/CC)
-  * View full email contents with attachments
-  * **Filter emails addressed to you directly (in To or CC)**
-
-* **Email Management**
-  * Mark emails as read/unread
-  * Delete or move emails between folders
-  * Organize emails with folder navigation
-
-* **Attachment Handling**
-  * List and download attachments
-  * Send emails with multiple attachments
-  * Support for various file types
-
-* **Contact Management**
-  * Retrieve contact list
-  * Perform smart contact searches
-  * Integration with Microsoft 365 address book
-
-### 🌟 Advanced Features
-
-* **Advanced Search Filters**
-  * Multi-folder search capabilities
-  * Keyword, date range, sender/recipient matching
-  * **Identify and filter emails where the user is in To or CC**
-  * Attachment and importance level filtering
-
-* **Smart Contact Intelligence**
-  * Automatically extract contact metadata
-  * Search by name, email, or company information
-
-* **Content Range Control**
-  * Load large emails in parts to improve performance
-  * Efficient pagination for large result sets
-
-* **Rich Email Format Support**
-  * Compose and display both plain text and HTML emails
-  * Proper MIME type handling
-
-* **Secure and Local Processing**
-  * All email operations are handled **locally**
-  * No data is forwarded to third-party servers
-  * OAuth2 compliance with Azure MSAL
+- **`logout`** - Clear authentication tokens and reset session
+- **`get_device_code`** - Get device code info for manual authentication
+
+**Total: 18 tools** (12 email operations + 6 authentication tools)
 
 ## 🚀 Quick Start
 
 ### Installation
 ```bash
-# Global installation (recommended)
+# Global installation
 npm install -g ms365-mcp-server
 
-# Quick device code authentication (no Azure app needed!)
+# Authenticate (no Azure app registration needed!)
 ms365-mcp-server --login
 
 # Start the server
@@ -129,353 +67,153 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
-### First Time Authentication  
-**Option 1: Device Code Flow (Recommended)**
-```bash
-ms365-mcp-server --login
-# Follow the on-screen instructions - no Azure app registration needed!
-```
+## 🔐 Authentication
 
-**Option 2: Interactive Setup**
+### Simple Setup (Recommended)
 ```bash
-ms365-mcp-server --setup-auth
-# Choose device code flow (recommended) or custom Azure app
-```
-
-## 🔐 **Enhanced Authentication System**
-
-Our MS365 MCP Server features a **dual-layer authentication system** inspired by [Softeria's implementation](https://github.com/Softeria/ms-365-mcp-server) with significant enhancements:
-
-### **🎯 Authentication Methods**
-
-1. **🔥 Device Code Flow (Recommended)**
-   - **No Azure app registration required**
-   - **Built-in Microsoft app** for instant setup
-   - **Secure device code authentication**
-   - Perfect for personal use and secure environments
-
-2. **⚙️ Custom Azure App (Advanced)**
-   - **Full control** over permissions and settings
-   - **Redirect-based OAuth2** authentication
-   - **Custom tenant configuration**
-   - Ideal for enterprise environments
-
-### **🔒 Secure Credential Storage**
-
-- **OS Keychain Integration** (macOS Keychain, Windows Credential Manager, Linux Secret Service)
-- **Encrypted File Fallback** for cross-platform compatibility
-- **Automatic token refresh** with MSAL library
-- **Multi-account support** with isolated storage
-
-### **⚡ New Authentication Commands**
-
-```bash
-# Device code authentication (easiest)
+# One-command authentication - no Azure registration required!
 ms365-mcp-server --login
-
-# Verify authentication status
-ms365-mcp-server --verify-login
-
-# Logout and clear tokens
-ms365-mcp-server --logout
-
-# Interactive credential setup
-ms365-mcp-server --setup-auth
-```
-
-### **🔄 Authentication Flow Comparison**
-
-| Feature | Device Code Flow *(Recommended)* | Redirect Flow *(Advanced)* |
-|---------|----------------------------------|----------------------------|
-| **Setup Required** | ❌ None (uses built-in app) | ✅ Azure app registration |
-| **Callback Endpoint** | ❌ Not needed | ✅ `http://localhost:44001/oauth2callback` |
-| **Port Requirements** | ❌ No ports needed | ✅ Port 44001 must be free |
-| **Browser Auto-open** | ❌ Manual code entry | ✅ Automatic browser redirect |
-| **Security** | 🔒 High (no local server) | 🔒 High (local callback) |
-| **Enterprise Support** | ✅ Excellent | ✅ Full control |
-
-**Most users should use Device Code Flow** - it's simpler, more secure, and requires no setup!
-
-## 🛠️ Installation & Setup
-
-### Global Installation
-
-```bash
-npm install -g ms365-mcp-server
 ```
 
-### Manual Installation
-
-```bash
-# Clone and build
-git clone <repository-url>
-cd ms365-mcp-server
-npm install
-npm run build
+### MCP Authentication Flow
+1. **Call**: `authenticate_with_device_code`
+2. **Get**: Device code and URL in the response
+3. **Visit**: https://microsoft.com/devicelogin  
+4. **Enter**: The provided device code
+5. **Call**: `authenticate_with_device_code` again
+6. **Done**: ✅ Authenticated and ready!
 
-# Set up authentication
-node dist/index.js --setup-auth
-
-# Start server
-node dist/index.js
-```
+### Advanced Setup (Custom Azure App)
+For advanced users who want custom Azure app configuration:
 
-## 🔑 Authentication Setup
-
-### Step 1: Azure App Registration *(Optional - Only for Advanced Users)*
-
-> **💡 Note**: Most users can skip this step! The recommended device code flow uses a built-in Microsoft app and doesn't require Azure app registration.
-
-**Only needed if you want a custom Azure app with redirect-based authentication:**
-
-1. Go to [Azure Portal](https://portal.azure.com)
-2. Navigate to **Azure Active Directory** > **App registrations**
-3. Click **"New registration"**
-4. Configure your application:
-   - **Name**: MS365 MCP Server (or your preferred name)
-   - **Supported account types**: Choose appropriate option
-   - **Redirect URI**: `http://localhost:44001/oauth2callback` *(only needed for redirect flow)*
-5. **Grant API permissions** for Microsoft Graph:
-   - `Mail.ReadWrite` - Read and write access to user mail
-   - `Mail.Send` - Send mail as user
-   - `MailboxSettings.Read` - Read user mailbox settings
-   - `Contacts.Read` - Read user contacts
-   - `User.Read` - Sign in and read user profile
-6. **Create client secret** in "Certificates & secrets"
-7. Note down:
-   - **Application (client) ID**
-   - **Directory (tenant) ID** 
-   - **Client secret value**
-
-### Step 2: Configure Credentials
-
-**Method 1: Environment Variables (Recommended)**
-```bash
-export MS365_CLIENT_ID="your_client_id_here"
-export MS365_CLIENT_SECRET="your_client_secret_here"
-export MS365_TENANT_ID="your_tenant_id_here"
-```
-
-**Method 2: Interactive Setup**
 ```bash
 ms365-mcp-server --setup-auth
-# Follow the prompts to enter your credentials
-```
-
-**Method 3: Credentials File**
-```bash
-# Save credentials to ~/.ms365-mcp/credentials.json
-{
-  "clientId": "your_client_id",
-  "clientSecret": "your_client_secret", 
-  "tenantId": "your_tenant_id",
-  "redirectUri": "http://localhost:44001/oauth2callback"
-}
-```
-
-### Step 3: Authentication Modes
-
-**Single-User Mode (Personal Use)**
-```bash
-ms365-mcp-server
-# Use quick_authenticate or get_auth_link tools
-```
-
-**Multi-User Mode (Teams/Shared)**
-```bash
-ms365-mcp-server --multi-user
-# Use authenticate_user tool for each user
+# Follow prompts for custom client ID/secret
 ```
 
 ## 📖 Usage Examples
 
-### Sending Emails
+### Email Operations
 ```javascript
+// Send an email with attachment
 {
   "tool": "send_email",
   "arguments": {
     "to": ["colleague@company.com"],
     "subject": "Project Update",
-    "body": "<h2>Status Report</h2><p>The project is <b>on track</b>!</p>",
+    "body": "<h2>Status Report</h2><p>Project is on track!</p>",
     "bodyType": "html",
-    "importance": "high",
     "attachments": [{
       "name": "report.pdf",
-      "contentBytes": "base64_encoded_content",
-      "contentType": "application/pdf"
+      "contentBytes": "base64_encoded_content"
     }]
   }
 }
-```
 
-### Advanced Email Search
-```javascript
+// Search emails with advanced criteria
 {
-  "tool": "search_emails",
+  "tool": "search_emails", 
   "arguments": {
     "from": "boss@company.com",
     "after": "2024-01-01",
-    "hasAttachment": true,
-    "isUnread": true,
-    "maxResults": 20
+    "hasAttachment": true
   }
 }
-```
 
-### Contact Search
-```javascript
+// Find all emails addressed to YOU (both TO and CC)
 {
-  "tool": "search_contacts",
+  "tool": "search_emails_to_me",
   "arguments": {
-    "query": "John Smith",
-    "maxResults": 10
+    "from": "important-sender@company.com",
+    "isUnread": true,
+    "after": "2024-01-01"
   }
 }
+
+// Check authentication
+{
+  "tool": "verify_authentication",
+  "arguments": {}
+}
 ```
 
-## 🎯 Command Line Options
+### 🔍 Email Search Options
 
-- `--setup-auth` - Configure Microsoft 365 API credentials
-- `--login` - Login using device code flow (recommended)
-- `--logout` - Logout and clear stored authentication tokens
-- `--verify-login` - Verify current authentication status
-- `--reset-auth` - Clear stored authentication tokens  
-- `--multi-user` - Enable multi-user authentication mode
-- `--debug` - Enable detailed debug logging
-- `--help` - Show help information
+- **`search_emails`** - General search with manual recipient specification
+  - Requires you to specify email addresses in `to` or `cc` fields
+  - More flexible for searching any recipient combinations
+  - Example: `{"to": "someone@company.com", "from": "boss@company.com"}`
 
-## 🔒 Security & Privacy
+- **`search_emails_to_me`** - Automatic search for emails addressed to YOU
+  - Automatically uses your email address for both TO and CC searches
+  - Finds ALL emails where you are a recipient (direct or CC'd)
+  - No need to specify your email address manually
+  - Example: `{"from": "boss@company.com", "isUnread": true}`
 
-- **Local token storage** in `~/.ms365-mcp/token.json`
-- **User isolation** in multi-user mode prevents cross-user data access
-- **OAuth2 compliance** with Microsoft MSAL library
-- **No external data transmission** - all data stays local
-- **Automatic token refresh** with secure credential management
+## 🎯 Command Line Options
 
-## 📊 Logging & Debugging
+- `--login` - Authenticate using device code flow (recommended)
+- `--logout` - Clear stored authentication tokens
+- `--verify-login` - Check current authentication status
+- `--setup-auth` - Interactive credential setup
+- `--reset-auth` - Clear all stored authentication data
+- `--debug` - Enable detailed debug logging
 
-Debug logs are written to: `/tmp/ms365-mcp-server.log`
+## 🛡️ Security Features
 
-Enable debug mode:
-```bash
-ms365-mcp-server --debug
-```
+- **Device Code Authentication** - No browser auto-open, manual code entry
+- **OS Keychain Integration** - Secure token storage with encrypted fallback
+- **Single-User Model** - Simplified security, no account enumeration
+- **Privacy Protection** - Users see only their own information
+- **OAuth2 Compliance** - Microsoft MSAL library with automatic refresh
+- **Local Processing** - No data transmitted to third-party servers
 
 ## 🚨 Troubleshooting
 
 ### Common Issues
 
 **"MS365 credentials not configured"**
-- Set environment variables or run `--setup-auth`
-- Ensure credentials file exists at correct path
+```bash
+ms365-mcp-server --login
+```
 
-**"Access blocked" during OAuth**
-- Verify your app has required Microsoft Graph permissions
-- Ensure redirect URI matches Azure app registration
+**Device code authentication issues**
+```bash
+ms365-mcp-server --verify-login  # Check status
+ms365-mcp-server --logout        # Reset if needed
+ms365-mcp-server --login         # Re-authenticate
+```
 
 **Authentication timeout**
+- Device codes expire in 15 minutes
 - Use `--reset-auth` to clear old tokens
-- Check that redirect URI matches Azure app settings
 
-**Permission errors**
-- Verify Microsoft Graph API permissions are granted in Azure Portal
-- Ensure admin consent is provided if required
-
-### Reset Authentication
+### Debug Logs
 ```bash
-ms365-mcp-server --reset-auth
+ms365-mcp-server --debug
+# Logs written to: /tmp/ms365-mcp-server.log
 ```
 
 ## 🔧 Development
 
-### Local Development
 ```bash
+# Local development
 npm run dev
-```
 
-### Build Project
-```bash
+# Build project
 npm run build
-```
-
-### Version Management
-```bash
-# Bump patch version (1.0.0 → 1.0.1)
-npm run version-bump
 
-# Bump minor version (1.0.0 → 1.1.0)
-npm run version-bump minor
-
-# Bump major version (1.0.0 → 2.0.0)
-npm run version-bump major
+# Version management
+npm run version-bump [patch|minor|major]
 ```
 
 ## 🧠 Perfect for AI Assistants
 
-- **Claude Desktop integration** - Add Microsoft 365 to your Claude conversations
-- **Personal email assistant** - Let AI help manage your inbox intelligently  
+- **Claude Desktop integration** - Add Microsoft 365 to Claude conversations
 - **Email automation** - Build smart workflows and email processing
-- **Email analysis** - Extract insights and patterns from your email data
-- **Customer support** - Streamline email-based customer interactions
-- **Research assistance** - Query and analyze email communications
-- **Email productivity** - Automate routine email tasks and responses
-
-## 🆚 **Enhanced Features vs Softeria's Implementation**
-
-While inspired by [Softeria's excellent MS365 MCP server](https://github.com/Softeria/ms-365-mcp-server), our implementation focuses on **email specialization** with significant enhancements:
-
-### **🎯 Our Email-First Advantages**
-
-| Feature | Our Implementation | Softeria's |
-|---------|-------------------|------------|
-| **Email Tools** | 11 comprehensive email tools | Basic mail operations |
-| **Authentication** | Device code + Redirect flows | Device code only |
-| **Storage Security** | OS Keychain + encrypted file | OS keychain fallback |
-| **Multi-user Support** | ✅ Full user isolation | ❌ Single user only |
-| **Email Search** | Advanced filtering & criteria | Basic search |
-| **Attachment Handling** | Full send/receive support | Basic attachment support |
-| **Documentation** | Comprehensive setup guides | Basic documentation |
-| **CLI Features** | Rich authentication commands | Basic login/logout |
-
-### **🚀 Unique Email Features**
-
-- **Advanced Email Filtering**: Filter by date ranges, attachments, importance, read status
-- **Multi-folder Search**: Search across all mailbox folders simultaneously  
-- **Email Organization**: Move emails between folders, mark read/unread status
-- **Contact Integration**: Full contact search and management
-- **Professional Email Composition**: HTML/text emails with attachments and CC/BCC
-- **Seamless Claude Integration**: Purpose-built for AI email assistance
-
-### **🔄 Migration from Softeria**
-
-If you're currently using Softeria's server and want **enhanced email capabilities**:
-
-```bash
-# Install our server
-npm install -g ms365-mcp-server
-
-# Quick authentication (uses built-in app like Softeria)
-ms365-mcp-server --login
-
-# Update Claude Desktop config
-{
-  "mcpServers": {
-    "ms365": {
-      "command": "ms365-mcp-server",
-      "args": []
-    }
-  }
-}
-```
-
-**Why Choose Our Implementation?**
-- **Email-specialized tools** for comprehensive mailbox management
-- **Multi-user support** for teams and shared environments
-- **Enhanced security** with OS keychain + encrypted file fallback
-- **Professional documentation** and troubleshooting guides
-- **Active development** focused on email productivity
-
-Both implementations are excellent - choose ours for **deep email functionality** or Softeria's for **broad Microsoft 365 integration**.
+- **Inbox management** - Let AI help organize and respond to emails
+- **Email analysis** - Extract insights and patterns from email data
+- **Customer support** - Streamline email-based interactions
 
 ## 📝 License
 
@@ -483,15 +221,10 @@ MIT License - see LICENSE file for details.
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-## 📞 Support
-
-For issues and questions:
-- Check the troubleshooting section above
-- Review debug logs in `/tmp/ms365-mcp-server.log`
-- Open an issue on the project repository
+Contributions welcome! Please feel free to submit a Pull Request.
 
 ---
 
-**Built with ❤️ for the AI and productivity community** 
+**Built with 🔒 Security and ❤️ for the AI community** 
+
+*Production-ready Microsoft 365 integration for Claude Desktop and MCP applications*