ms365-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 MS365 MCP Server
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,497 @@
+# ✉️ 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**.
+
+## ✨ 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
+- **Contact management** - retrieve and search your contact directory
+- **Secure authentication** with local token storage and automatic refresh
+- **Cross-platform compatibility** (macOS, Linux, Windows)
+
+## 🛠️ Tools & Capabilities
+
+### 📧 Core Email Operations (11 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
+- **`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
+- **`move_email`** - Move emails between folders
+- **`delete_email`** - Permanently delete email messages
+- **`list_folders`** - Browse all mail folders and their statistics
+- **`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
+- **`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
+
+## 🚀 Quick Start
+
+### Installation
+```bash
+# Global installation (recommended)
+npm install -g ms365-mcp-server
+
+# Quick device code authentication (no Azure app needed!)
+ms365-mcp-server --login
+
+# Start the server
+ms365-mcp-server
+```
+
+### Claude Desktop Integration
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ms365": {
+      "command": "ms365-mcp-server",
+      "args": []
+    }
+  }
+}
+```
+
+### First Time Authentication  
+**Option 1: Device Code Flow (Recommended)**
+```bash
+ms365-mcp-server --login
+# Follow the on-screen instructions - no Azure app registration needed!
+```
+
+**Option 2: Interactive Setup**
+```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)
+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
+
+# Set up authentication
+node dist/index.js --setup-auth
+
+# Start server
+node dist/index.js
+```
+
+## 🔑 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
+```
+
+## 📖 Usage Examples
+
+### Sending Emails
+```javascript
+{
+  "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>",
+    "bodyType": "html",
+    "importance": "high",
+    "attachments": [{
+      "name": "report.pdf",
+      "contentBytes": "base64_encoded_content",
+      "contentType": "application/pdf"
+    }]
+  }
+}
+```
+
+### Advanced Email Search
+```javascript
+{
+  "tool": "search_emails",
+  "arguments": {
+    "from": "boss@company.com",
+    "after": "2024-01-01",
+    "hasAttachment": true,
+    "isUnread": true,
+    "maxResults": 20
+  }
+}
+```
+
+### Contact Search
+```javascript
+{
+  "tool": "search_contacts",
+  "arguments": {
+    "query": "John Smith",
+    "maxResults": 10
+  }
+}
+```
+
+## 🎯 Command Line 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
+
+## 🔒 Security & Privacy
+
+- **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
+
+## 📊 Logging & Debugging
+
+Debug logs are written to: `/tmp/ms365-mcp-server.log`
+
+Enable debug mode:
+```bash
+ms365-mcp-server --debug
+```
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+**"MS365 credentials not configured"**
+- Set environment variables or run `--setup-auth`
+- Ensure credentials file exists at correct path
+
+**"Access blocked" during OAuth**
+- Verify your app has required Microsoft Graph permissions
+- Ensure redirect URI matches Azure app registration
+
+**Authentication timeout**
+- 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
+```bash
+ms365-mcp-server --reset-auth
+```
+
+## 🔧 Development
+
+### Local Development
+```bash
+npm run dev
+```
+
+### Build Project
+```bash
+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
+```
+
+## 🧠 Perfect for AI Assistants
+
+- **Claude Desktop integration** - Add Microsoft 365 to your Claude conversations
+- **Personal email assistant** - Let AI help manage your inbox intelligently  
+- **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**.
+
+## 📝 License
+
+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
+
+---
+
+**Built with ❤️ for the AI and productivity community**