Umbrella MCP Server

# Desktop Client Integration Guide for Umbrella MCP ## Common Natural Language Questions → MCP Tool Mapping ### 1. Customer/MSP Questions **User asks:** "show me the list of customers" **Desktop client should:** 1. Call `authenticate_user` first if not authenticated 2. Call `api___msp_customers` tool 3. If that fails with 403/500, try `api___user_management_accounts` as fallback 4. Format response as a list of customer names **Expected response pattern:** ``` 📊 **MSP Customers:** 1. Customer A (Account: xxx) 2. Customer B (Account: yyy) ``` ### 2. Total Cost Questions **User asks:** "what is my total cost?" / "what are the total costs?" **Desktop client should:** 1. Call `get_umbrella_guidance` with query_type="cost" 2. Call `api___user_management_accounts` to get available accounts 3. Call `api___invoices_caui` with specific account (not ALL ACCOUNTS) 4. Use current month date range if no dates specified 5. Present cost with proper currency formatting **Expected response pattern:** ``` 💰 **Total Cost Analysis** **Period:** [date range] **Account:** [account name] **Total Cost:** $X,XXX.XX **Cost Type:** [unblended/amortized/net amortized] ``` ### 3. Service-Specific Cost Questions **User asks:** "what is my total AWS cost?" **Desktop client should:** 1. Call `get_umbrella_guidance` with query_type="cost" and service_name="aws" 2. Filter accounts by cloud_context="aws" or cloudTypeId=0 3. Call `api___invoices_caui` with AWS-specific accounts 4. Sum costs across AWS accounts ### 4. Recommendation Questions **User asks:** "what do you recommend for saving AWS costs?" **Desktop client should:** 1. Call `get_umbrella_guidance` with query_type="recommendations" 2. Call `api___user_management_accounts` to get specific accounts (NOT ALL ACCOUNTS) 3. Call `api___apiv2recommendationslist` with specific account filter 4. Format as actionable recommendations list **Expected response pattern:** ``` 🎯 **AWS Cost Optimization Recommendations** **Account:** [specific account name] 1. **EC2 Right-sizing:** Save $XXX/month - Action: Resize 5 underutilized instances 2. **Storage Optimization:** Save $XXX/month - Action: Archive unused EBS volumes ``` ### 5. Anomaly Detection Questions **User asks:** "Is there any anomalies on AWS?" **Desktop client should:** 1. Call `get_umbrella_guidance` with query_type="anomalies" 2. Call `api___anomaly_detection` with AWS-specific filters 3. Filter to OPEN anomalies only (unless closed explicitly requested) 4. Present with severity levels and dates ## Key Desktop Client Rules ### Authentication Flow ``` 1. User opens desktop client 2. Client calls: authenticate_user(username, password) 3. Client stores session info internally 4. All subsequent API calls include session context ``` ### Error Handling - **403 Forbidden**: Show "Access denied - check permissions" - **500 Server Error**: Show "Service temporarily unavailable" - **Empty results**: Show "No data available for this period/account" - **API failures**: Follow "no-fallback" rule - don't try multiple endpoints ### Response Formatting for Desktop - Use **markdown formatting** for better readability - Include **emojis** for visual categorization (💰 for costs, 🎯 for recommendations) - Show **exact numbers** from API (never estimate or extrapolate) - Include **date ranges** and **account names** in every response - Format large numbers with commas: `$1,234.56` ### Natural Language Interpretation Tips - "total cost" → current month, specific account (not ALL ACCOUNTS) - "monthly cost" → group by month, show time series - "last X months" → calculate date range from current date backward - "amortized" → use isAmortized=true parameter - "net amortized" → use isNetAmortized=true parameter - "recommendations" → require specific account selection - "anomalies" → filter to open only, specific account ### Required Tool Sequence Examples **Question: "Show me costs for last 3 months"** ``` 1. get_umbrella_guidance(query_type="cost") 2. api___user_management_accounts() 3. Calculate start_date = 3 months ago, end_date = today 4. api___invoices_caui(startDate, endDate, accountId=specific_account, groupBy="none", periodGranLevel="month") ``` **Question: "What AWS services am I using?"** ``` 1. get_umbrella_guidance(query_type="service-analysis", service_name="aws") 2. api___user_management_accounts() → filter AWS accounts 3. api___invoices_service_names_distinct() → filter by cloud provider 4. Present as categorized service list ``` ## Desktop Client Testing Checklist ✅ **Authentication** - [ ] Username/password authentication works - [ ] Session persistence across tool calls - [ ] Proper error messages for auth failures ✅ **Natural Language Processing** - [ ] "show me customers" → calls MSP customer endpoints - [ ] "total costs" → calls cost APIs with proper parameters - [ ] "recommendations" → calls recommendation APIs with account filters - [ ] "anomalies" → calls anomaly detection with open filter ✅ **Response Formatting** - [ ] Costs display with currency symbols and commas - [ ] Dates show in readable format - [ ] Account names are clearly indicated - [ ] Error messages are user-friendly ✅ **Edge Cases** - [ ] Empty result sets handled gracefully - [ ] API timeouts show appropriate messages - [ ] Permission denied scenarios explained clearly - [ ] No data periods indicated properly ## Common Desktop Client Issues & Fixes **Issue:** Questions return empty or generic responses **Fix:** Ensure client calls `get_umbrella_guidance` before API calls **Issue:** "Access denied" for customer questions **Fix:** Check if account has MSP permissions, show appropriate message **Issue:** Cost numbers appear as raw API responses **Fix:** Format numbers with currency symbols and thousand separators **Issue:** Recommendations fail with "not configured" **Fix:** Use specific account IDs, not aggregated accounts **Issue:** Date ranges don't work as expected **Fix:** Use current year dates, calculate backward from today's date