ms365-mcp-server 1.0.5 → 1.1.0

package/README.md

@@ -1,61 +1,57 @@
 # ✉️ 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 with **production-ready security**.
+A powerful **Model Context Protocol (MCP) server** that enables seamless Microsoft 365 email integration through natural language interactions. Built for **SIYA 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
-- **File attachment support** - send and receive attachments seamlessly
-- **Enhanced security** with simplified single-user authentication model
-- **Contact management** - retrieve and search your contact directory
-- **Secure authentication** with OS keychain storage and automatic refresh
-- **Cross-platform compatibility** (macOS, Linux, Windows)
-
-## 🛠️ Tools & Capabilities
-
-### 📧 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 intelligent partial name matching
-- **`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
-- **`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 (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
-- **`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)
+- **🎯 Optimized Tool Architecture** - Only 6 unified tools (67% reduction from 18 tools)
+- **📧 Complete Email Management** - Send, read, search, organize, and manage attachments
+- **🔐 Bulletproof Authentication** - Proactive token refresh prevents chat interruptions
+- **🤖 AI-First Design** - Intuitive action-based tools perfect for LLM interactions
+- **🔒 Enterprise Security** - OAuth2 with secure keychain storage and automatic refresh
+- **📁 Smart Contact Management** - Search and retrieve your Microsoft 365 contacts
+- **🌐 Cross-Platform** - Works on macOS, Linux, and Windows
+
+## 🛠️ Available Tools (6 Total)
+
+### **📧 Email Management**
+- **`send_email`** - Send emails with attachments and rich formatting
+- **`manage_email`** - **UNIFIED**: Read, search, list, mark, move, or delete emails
+- **`get_attachment`** - Download email attachments with metadata
+- **`list_folders`** - Browse mailbox folders with item counts
+
+### **👥 Contacts & Authentication**
+- **`manage_contacts`** - **UNIFIED**: List all contacts or search by name/email
+- **`authenticate`** - **UNIFIED**: Complete authentication management (login, status, logout)
 
 ## 🚀 Quick Start
 
-### Installation
+### 1. Installation
+
+**Option A: Global Installation**
 ```bash
-# Global installation
+# Install globally
 npm install -g ms365-mcp-server
 
-# Authenticate (no Azure app registration needed!)
+# Authenticate (no Azure setup needed!)
 ms365-mcp-server --login
 
 # Start the server
 ms365-mcp-server
 ```
 
-### Claude Desktop Integration
-Add to your `claude_desktop_config.json`:
+**Option B: Run with npx (no installation needed)**
+```bash
+# Authenticate
+npx ms365-mcp-server --login
 
+# Start the server
+npx ms365-mcp-server
+```
+
+### 2. SIYA Desktop Integration
+
+**For Global Installation:**
 ```json
 {
   "mcpServers": {
@@ -67,31 +63,57 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
+**For npx Usage:**
+```json
+{
+  "mcpServers": {
+    "ms365": {
+      "command": "npx",
+      "args": ["ms365-mcp-server"]
+    }
+  }
+}
+```
+
+### 3. Start Using
+Chat with SIYA and ask it to help with your emails! The tools are designed for natural language interaction.
+
 ## 🔐 Authentication
 
 ### Simple Setup (Recommended)
 ```bash
-# One-command authentication - no Azure registration required!
+# One-command authentication
 ms365-mcp-server --login
 ```
 
-### 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!
+### MCP Tool Authentication
+```javascript
+// Check authentication status
+{
+  "tool": "authenticate",
+  "arguments": {
+    "action": "status"
+  }
+}
 
-### Advanced Setup (Custom Azure App)
-For advanced users who want custom Azure app configuration:
+// Login with device code
+{
+  "tool": "authenticate", 
+  "arguments": {
+    "action": "login"
+  }
+}
 
-```bash
-ms365-mcp-server --setup-auth
-# Follow prompts for custom client ID/secret
+// Logout
+{
+  "tool": "authenticate",
+  "arguments": {
+    "action": "logout"
+  }
+}
 ```
 
-## 📖 Usage Examples
+## 💡 Tool Usage Examples
 
 ### Email Operations
 ```javascript
@@ -110,91 +132,166 @@ ms365-mcp-server --setup-auth
   }
 }
 
-// Search emails with advanced criteria
+// Search emails with smart name matching
 {
-  "tool": "search_emails", 
+  "tool": "manage_email",
   "arguments": {
-    "from": "boss@company.com",
+    "action": "search",
+    "from": "John Smith",  // Works with names or emails
     "after": "2024-01-01",
     "hasAttachment": true
   }
 }
 
-// Find all emails addressed to YOU (both TO and CC)
+// List recent inbox emails
 {
-  "tool": "search_emails_to_me",
+  "tool": "manage_email",
   "arguments": {
-    "from": "important-sender@company.com",
-    "isUnread": true,
-    "after": "2024-01-01"
+    "action": "list",
+    "folderId": "inbox", 
+    "maxResults": 10
   }
 }
 
-// Check authentication
+// Find emails sent to you (TO or CC)
 {
-  "tool": "verify_authentication",
-  "arguments": {}
+  "tool": "manage_email",
+  "arguments": {
+    "action": "search_to_me",
+    "from": "boss@company.com",
+    "isUnread": true
+  }
+}
+
+// Read a specific email
+{
+  "tool": "manage_email",
+  "arguments": {
+    "action": "read",
+    "messageId": "email_id_here"
+  }
+}
+
+// Mark email as read
+{
+  "tool": "manage_email",
+  "arguments": {
+    "action": "mark",
+    "messageId": "email_id",
+    "isRead": true
+  }
+}
+
+// Move email to folder
+{
+  "tool": "manage_email",
+  "arguments": {
+    "action": "move",
+    "messageId": "email_id",
+    "destinationFolderId": "archive"
+  }
+}
+
+// Delete email
+{
+  "tool": "manage_email",
+  "arguments": {
+    "action": "delete",
+    "messageId": "email_id"
+  }
 }
 ```
 
-### 🔍 Email Search Options
+### Contact & Authentication
+```javascript
+// List all contacts
+{
+  "tool": "manage_contacts",
+  "arguments": {
+    "action": "list",
+    "maxResults": 100
+  }
+}
+
+// Search contacts by name
+{
+  "tool": "manage_contacts", 
+  "arguments": {
+    "action": "search",
+    "query": "John"
+  }
+}
 
-- **`search_emails`** - Unified search with intelligent capabilities
-  - **Smart Name Matching**: Automatically detects names vs email addresses
-  - **Partial Name Support**: Search by "Madan", "Kumar", "M Kumar", etc.
-  - **Flexible Criteria**: Combine name search with date ranges, subjects, etc.
-  - **Email Address Matching**: Use exact email addresses when needed
-  - Example: `{"from": "Madan", "after": "2024-01-01"}` or `{"from": "boss@company.com"}`
+// Get attachment from email
+{
+  "tool": "get_attachment",
+  "arguments": {
+    "messageId": "email_id",
+    "attachmentId": "attachment_id"
+  }
+}
 
-- **`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}`
+// List mailbox folders
+{
+  "tool": "list_folders",
+  "arguments": {}
+}
+```
 
 ## 🎯 Command Line Options
 
-- `--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
+```bash
+# Authentication
+ms365-mcp-server --login         # Authenticate using device code
+ms365-mcp-server --logout        # Clear stored tokens
+ms365-mcp-server --verify-login  # Check authentication status
+
+# Management  
+ms365-mcp-server --setup-auth    # Interactive credential setup
+ms365-mcp-server --reset-auth    # Clear all authentication data
+ms365-mcp-server --debug         # Enable detailed logging
+```
 
-## 🛡️ Security Features
+## 🛡️ Security & Reliability
 
-- **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
+- **🔄 Proactive Token Refresh** - Prevents authentication interruptions during long conversations
+- **🔐 Secure Storage** - OS keychain integration with encrypted fallback
+- **🛡️ OAuth2 Compliance** - Microsoft MSAL library with enterprise-grade security
+- **🏠 Privacy First** - All processing happens locally, no data sent to third parties
+- **🔒 Single-User Model** - Simplified security without account enumeration risks
 
 ## 🚨 Troubleshooting
 
-### Common Issues
-
-**"MS365 credentials not configured"**
+### Authentication Issues
 ```bash
+# Check current status
+ms365-mcp-server --verify-login
+
+# Reset and re-authenticate
+ms365-mcp-server --logout
 ms365-mcp-server --login
 ```
 
-**Device code authentication issues**
+### Debug Mode
 ```bash
-ms365-mcp-server --verify-login  # Check status
-ms365-mcp-server --logout        # Reset if needed
-ms365-mcp-server --login         # Re-authenticate
+# Enable detailed logging
+ms365-mcp-server --debug
+
+# Logs location: /tmp/ms365-mcp-server.log
 ```
 
-**Authentication timeout**
-- Device codes expire in 15 minutes
-- Use `--reset-auth` to clear old tokens
+### Common Solutions
+- **"Credentials not configured"** → Run `--login`
+- **"Token expired"** → Authentication auto-refreshes, or run `--login`
+- **Device code timeout** → Codes expire in 15 minutes, try `--login` again
 
-### Debug Logs
-```bash
-ms365-mcp-server --debug
-# Logs written to: /tmp/ms365-mcp-server.log
-```
+## 🧠 Perfect for AI Assistants
+
+- **📞 Natural Language Interface** - Ask SIYA to "check my emails from John today"
+- **🤖 Smart Email Processing** - Let AI help organize, respond, and analyze emails
+- **⚡ Optimized for LLMs** - Unified tools reduce context switching and improve performance
+- **🔄 Reliable Sessions** - Proactive authentication prevents chat interruptions
+- **📊 Email Analytics** - Extract insights and patterns from your email data
 
 ## 🔧 Development
 
@@ -202,20 +299,21 @@ ms365-mcp-server --debug
 # Local development
 npm run dev
 
-# Build project
+# Build and test
 npm run build
+npm test
 
-# Version management
+# Version management  
 npm run version-bump [patch|minor|major]
 ```
 
-## 🧠 Perfect for AI Assistants
+## 📈 What's New in v1.1.0
 
-- **Claude Desktop integration** - Add Microsoft 365 to Claude conversations
-- **Email automation** - Build smart workflows and email processing
-- **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
+- **🎯 67% Fewer Tools** - Consolidated 18 tools into 6 unified tools
+- **🔄 Bulletproof Auth** - Proactive token refresh prevents interruptions
+- **⚡ Better Performance** - Optimized tool architecture for faster responses
+- **🧠 AI-Optimized** - Action-based design perfect for LLM interactions 
+- **🛡️ Enhanced Security** - Improved error handling and retry logic
 
 ## 📝 License
 
@@ -223,10 +321,10 @@ MIT License - see LICENSE file for details.
 
 ## 🤝 Contributing
 
-Contributions welcome! Please feel free to submit a Pull Request.
+Contributions welcome! Please submit issues and pull requests.
 
 ---
 
-**Built with 🔒 Security and ❤️ for the AI community** 
+**Built with 🔒 Security and ❤️ for the AI community**
 
-*Production-ready Microsoft 365 integration for Claude Desktop and MCP applications*
+*Production-ready Microsoft 365 integration for SIYA Desktop and MCP applications*

package/bin/cli.js

@@ -64,7 +64,7 @@ let login = false;
 let logout = false;
 let verifyLogin = false;
 
-// Detect if we're running under an MCP context (Claude/ChatGPT/etc.)
+// Detect if we're running under an MCP context (Claude/SIYA/ChatGPT/etc.)
 const isMcpContext = 
   !process.stdin.isTTY || 
   process.env.npm_execpath?.includes('npx') ||
@@ -106,7 +106,7 @@ for (let i = 0; i < args.length; i++) {
     writeDebug('Verify login mode enabled');
   } else if (arg === '--help' || arg === '-h') {
     console.log(`
-MS365 MCP Server - Microsoft 365 Integration for Claude Desktop
+MS365 MCP Server - Microsoft 365 Integration for Claude/SIYA Desktop
 
 Usage: npx ms365-mcp-server [options]