Microsoft 365 Core MCP Server

# Microsoft 365 Core MCP Server - Lazy Loading Implementation ## 🎯 **Problem Solved** **Before:** Tools were invisible on Smithery because the server required Microsoft 365 credentials during initialization. **After:** Server starts successfully without credentials, making all 40+ tools discoverable while deferring authentication until actual tool execution. ## 🚀 **Implementation Changes** ### **1. Modified `getGraphClient()` Method** **Before:** ```typescript private getGraphClient(): Client { if (!this.graphClient) { this.validateCredentials(); // ❌ Failed here if no credentials this.graphClient = Client.init({...}); } return this.graphClient; } ``` **After:** ```typescript private getGraphClient(): Client { if (!this.graphClient) { // ✅ No early validation - deferred to authProvider this.graphClient = Client.init({ authProvider: async (callback) => { try { this.validateCredentials(); // ✅ Validate only when token needed const token = await this.getAccessToken(apiConfigs.graph.scope); callback(null, token); } catch (error) { callback(error, null); } } }); } return this.graphClient; } ``` ### **2. Added Non-Throwing Credential Check** ```typescript private hasValidCredentials(): boolean { const requiredEnvVars = ['MS_TENANT_ID', 'MS_CLIENT_ID', 'MS_CLIENT_SECRET']; return requiredEnvVars.every(varName => !!process.env[varName]); } ``` ### **3. Added Health Check Tool (No Auth Required)** ```typescript this.server.tool( "health_check", "Check server status and authentication configuration without requiring credentials", z.object({}).shape, wrapToolHandler(async () => { const hasCredentials = this.hasValidCredentials(); return { content: [{ type: "text", text: `M365 Core MCP Server Health Check\n\n` + `Status: ${hasCredentials ? 'Ready' : 'Requires Configuration'}` }] }; }) ); ``` ## 📊 **Authentication Flow** ### **1. Server Startup Phase** ``` Server Creation → Tool Registration → Resource Setup → Ready for Discovery ↓ ↓ ↓ ↓ No auth needed No auth needed No auth needed All tools visible ``` ### **2. Tool Discovery Phase (Smithery)** ``` List Tools → Get Tool Schemas → Show Descriptions → User Selection ↓ ↓ ↓ ↓ Available Available Available Ready to execute ``` ### **3. Tool Execution Phase** ``` User Calls Tool → Validate Credentials → Get Token → Call Microsoft API ↓ ↓ ↓ ↓ Parameters Check env vars OAuth flow Graph API call ``` ## ✅ **Benefits for Smithery** ### **🔍 Tool Discovery** - Server starts without requiring environment variables - All 40+ tools immediately visible and discoverable - Tool schemas and descriptions accessible for introspection - Proper capability advertisement ### **🛠️ Graceful Degradation** - Health check tool works without authentication - Clear error messages when credentials missing - Non-blocking server initialization - Progressive enhancement approach ### **👨‍� Developer Experience** - Server can be tested and explored without setup - Authentication configuration is optional for discovery - Clear feedback about what's needed for execution - Standard MCP server behavior ## 🔧 **Tool Categories** ### **✅ Always Available (No Auth Required)** - `health_check` - Server status and configuration check ### **🔐 Authentication Required (Lazy Loaded)** - `manage_distribution_lists` - Exchange distribution list management - `manage_security_groups` - Azure AD security group operations - `manage_m365_groups` - Microsoft 365 group administration - `create_intune_policy` - Intune policy creation with validation - All other Microsoft 365 management tools (40+ total) ## 🌍 **Environment Variables** **Required for tool execution (not for discovery):** - `MS_TENANT_ID` - Azure AD tenant ID - `MS_CLIENT_ID` - Azure AD application (client) ID - `MS_CLIENT_SECRET` - Azure AD application client secret **Optional:** - `PORT` - HTTP server port (default: 3000) - `LOG_LEVEL` - Logging level (default: info) - `NODE_ENV` - Environment mode (stdio/http) ## 📚 **Usage with Smithery** ### **1. Server Registration** ```bash # Server can be registered without environment variables # Tools will be immediately visible in Smithery interface ``` ### **2. Tool Discovery** - All tools visible in Smithery catalog - Rich descriptions and parameter schemas available - No authentication required for browsing capabilities ### **3. Configuration** - Set environment variables when ready to execute tools - Use `health_check` tool to verify configuration - Get setup instructions and status information ### **4. Execution** - Tools validate credentials on first execution - Tokens are cached for subsequent calls - Rate limiting and error handling active ## 🚨 **Error Handling** ### **Server Startup** ``` ✅ Success: Server starts regardless of credential availability ✅ Success: All tools registered and visible ✅ Success: Resources available for discovery ``` ### **Tool Execution** ``` ❌ Missing Credentials: Clear error message with setup instructions Links to Azure AD app registration documentation ✅ Valid Credentials: Successful authentication and API calls Token caching for performance Rate limiting for API protection ``` ## 🧪 **Testing the Implementation** ### **Verify Lazy Loading** ```bash # Test without credentials unset MS_TENANT_ID MS_CLIENT_ID MS_CLIENT_SECRET npm run build npm start # Server should start successfully # Tools should be visible to discovery systems ``` ### **Verify Authentication** ```bash # Test with credentials export MS_TENANT_ID="your-tenant-id" export MS_CLIENT_ID="your-client-id" export MS_CLIENT_SECRET="your-client-secret" # Tools should execute successfully # API calls should work properly ``` ## � **Migration Guide** ### **For Existing Users** 1. **No Changes Required** - Server works exactly as before when credentials are configured 2. **New Capability** - Server now works without credentials for discovery 3. **Enhanced Experience** - Better error messages and health check tool ### **For New Users** 1. **Easy Discovery** - Register server without setup requirements 2. **Gradual Setup** - Configure authentication when ready to use tools 3. **Clear Guidance** - Health check tool provides setup instructions ## 🎉 **Summary** The lazy loading implementation ensures the M365 Core MCP Server is fully compatible with Smithery while maintaining security and functionality. Tools are discoverable without authentication, but actual Microsoft 365 operations still require proper credentials and permissions. **🎯 Key Achievement:** Server visibility and tool discovery work immediately, while authentication is enforced only when actually needed for Microsoft 365 API operations. **🚀 Result:** All 40+ tools are now visible on Smithery and ready for discovery and execution! ## 🛠 **Environment Variables** When users try to execute tools, they'll get helpful guidance: ``` Missing required environment variables for Microsoft 365 authentication: - MS_TENANT_ID: Your Azure AD tenant ID - MS_CLIENT_ID: Your Azure AD application (client) ID - MS_CLIENT_SECRET: Your Azure AD application client secret For setup instructions, visit: https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app ``` ## 📊 **Registry Compatibility** Your server is now optimized for: - ✅ **Smithery** - Tool discovery and exploration - ✅ **MCP Inspector** - Development and testing - ✅ **Claude Desktop** - Direct integration - ✅ **Other MCP Clients** - Universal compatibility ## 🎉 **Ready for Production** Your M365 Core MCP server now follows MCP best practices and is ready for: - Registration in tool directories - Distribution to users - Integration with AI assistants - Enterprise deployment Users can now discover your tools first, then configure their credentials to use them!