Umbrella MCP Server

#!/usr/bin/env node

/**
 * UMBRELLA MCP SERVER: get_all_recommendations TOOL ANALYSIS
 * 
 * This script analyzes where and how the `get_all_recommendations` tool is handled in the MCP server code.
 * Based on user feedback:
 * - For direct customer accounts: get_all_recommendations works perfectly fine
 * - For MSP accounts: The tool fails because it needs customer detection from natural language queries
 */

console.log('='.repeat(80));
console.log('UMBRELLA MCP SERVER: get_all_recommendations TOOL ANALYSIS');
console.log('='.repeat(80));

console.log('\n🔍 FINDINGS SUMMARY:');
console.log('-------------------');

console.log('\n1. TOOL REGISTRATION:');
console.log('   ✅ Tool is dynamically registered from UMBRELLA_ENDPOINTS array');
console.log('   📍 Location: /Users/david/Downloads/MCP/UmbrellaMCP/src/types.ts:192-203');
console.log('   📄 Endpoint Definition:');
console.log('   {');
console.log('     path: "/api/v2/recommendations/list",');
console.log('     method: "POST",');
console.log('     description: "Get all recommendations with pagination support. Returns detailed recommendations with savings potential",');
console.log('     category: "Recommendations",');
console.log('     parameters: {');
console.log('       "filters": "JSON object with user_status, status_filter, and date ranges",');
console.log('       "sort": "Array of sort objects with by and order fields",');
console.log('       "page_size": "Number of recommendations per page (default 2000)",');
console.log('       "pagination_token": "Token for fetching next page of results",');
console.log('       "userQuery": "Natural language query from user - used for customer detection"');
console.log('     }');
console.log('   }');

console.log('\n2. TOOL NAME GENERATION:');
console.log('   📍 Location: /Users/david/Downloads/MCP/UmbrellaMCP/src/server.ts:107-129');
console.log('   🔧 Algorithm: api__${path.replace(/\\//g, \'_\').replace(/[-]/g, \'_\')}');
console.log('   📝 Expected Tool Name: "api__api_v2_recommendations_list"');
console.log('   ❌ NOT "get_all_recommendations" (user might be using wrong name)');

console.log('\n3. TOOL CALL HANDLING:');
console.log('   📍 Location: /Users/david/Downloads/MCP/UmbrellaMCP/src/server.ts:196-218');
console.log('   🔧 Flow: name.startsWith("api__") → find endpoint → handleApiCall()');
console.log('   📍 handleApiCall: /Users/david/Downloads/MCP/UmbrellaMCP/src/server.ts:535-1235');

console.log('\n4. MSP CUSTOMER DETECTION:');
console.log('   📍 Location: /Users/david/Downloads/MCP/UmbrellaMCP/src/server.ts:764-821');
console.log('   🔧 Method: detectCustomerFromQuery()');
console.log('   📍 Implementation: /Users/david/Downloads/MCP/UmbrellaMCP/src/server.ts:1270-1546');
console.log('   ✅ ALREADY IMPLEMENTED for recommendation endpoints');
console.log('   🎯 Detection Logic:');
console.log('     - Only for MSP users (cognito auth method)');
console.log('     - Only for recommendation/cost-related endpoints (includes /recommendations)');
console.log('     - Analyzes userQuery parameter for customer names');
console.log('     - Maps customer names to account keys and division IDs');

console.log('\n5. API CLIENT FLOW:');
console.log('   📍 Location: /Users/david/Downloads/MCP/UmbrellaMCP/src/api-client.ts:84-97');
console.log('   🔧 General Flow: makeRequest() → makeDirectRequest()');
console.log('   📍 Special Recommendations Method: /Users/david/Downloads/MCP/UmbrellaMCP/src/api-client.ts:412-558');
console.log('   🔧 Dedicated getRecommendations() method with:');
console.log('     - Hardcoded V2 API endpoint: https://api.umbrellacost.io/api/v2/recommendations/list');
console.log('     - POST method with specific request body');
console.log('     - Pagination support');
console.log('     - 12-month date range default');

console.log('\n6. THE ISSUE ANALYSIS:');
console.log('   🤔 Based on the code analysis, the MSP customer detection is ALREADY implemented.');
console.log('   🧐 Possible causes of MSP account failures:');

console.log('\n   A. TOOL NAME MISMATCH:');
console.log('      ❌ User calls: "get_all_recommendations"');
console.log('      ✅ Actual name: "api__api_v2_recommendations_list"');
console.log('      💡 Solution: Use correct tool name or add alias');

console.log('\n   B. MISSING userQuery PARAMETER:');
console.log('      🎯 Customer detection requires "userQuery" parameter');
console.log('      📝 Example: userQuery="Show me Bank Leumi recommendations"');
console.log('      💡 Solution: Ensure Claude Desktop passes userQuery');

console.log('\n   C. AUTHENTICATION METHOD CHECK:');
console.log('      🔍 Detection only works for cognito auth (MSP users)');
console.log('      📍 Check: session.auth.getUserManagementInfo()?.authMethod === "cognito"');
console.log('      💡 Solution: Verify MSP account uses cognito auth');

console.log('\n   D. API FLOW CONFLICT:');
console.log('      🔄 Two paths to recommendations:');
console.log('      1. Generic: makeRequest("/api/v2/recommendations/list") via handleApiCall()');
console.log('      2. Dedicated: getRecommendations() method');
console.log('      ⚠️  The dedicated method bypasses MCP customer detection logic!');

console.log('\n7. ROOT CAUSE IDENTIFIED:');
console.log('   🎯 THE PROBLEM: Dedicated getRecommendations() method bypasses MCP server logic');
console.log('   📍 Location: /Users/david/Downloads/MCP/UmbrellaMCP/src/api-client.ts:412-558');
console.log('   🔧 This method:');
console.log('     - Makes direct axios.post() call to hardcoded URL');
console.log('     - Bypasses makeDirectRequest() and MCP customer detection');
console.log('     - Only uses getAuthHeaders() without customer context');
console.log('     - Works for direct customers (single account)');
console.log('     - Fails for MSP customers (needs account switching)');

console.log('\n8. SOLUTION OPTIONS:');

console.log('\n   OPTION 1: Ensure MCP Tool Uses makeRequest (RECOMMENDED)');
console.log('   📍 Problem: The api__api_v2_recommendations_list tool should use makeRequest(), not getRecommendations()');
console.log('   🔧 Check server.ts:927 - does it call session.apiClient.makeRequest() or getRecommendations()?');
console.log('   ✅ If it uses makeRequest(), customer detection will work');

console.log('\n   OPTION 2: Add Customer Detection to getRecommendations()');
console.log('   📍 Modify: /Users/david/Downloads/MCP/UmbrellaMCP/src/api-client.ts:412-558');
console.log('   🔧 Add customer_account_key parameter handling');
console.log('   🔧 Extract customer info from params before making axios call');
console.log('   🔧 Include customer context in auth headers');

console.log('\n   OPTION 3: Add Tool Name Alias');
console.log('   📍 Modify: /Users/david/Downloads/MCP/UmbrellaMCP/src/server.ts');
console.log('   🔧 Add special case for "get_all_recommendations" → "api__api_v2_recommendations_list"');

console.log('\n9. VERIFICATION STEPS:');
console.log('   1. Check which API client method is called by the MCP tool');
console.log('   2. Verify MSP account uses cognito authentication');
console.log('   3. Ensure userQuery parameter is passed from Claude Desktop');
console.log('   4. Test customer detection with debug logging');
console.log('   5. Verify auth headers include customer context');

console.log('\n10. DEBUG COMMANDS:');
console.log('    # Check actual tool call in server logs');
console.log('    grep "api__api_v2_recommendations_list" server_logs.txt');
console.log('');
console.log('    # Check customer detection logs');
console.log('    grep "CUSTOMER-DETECTION" server_logs.txt');
console.log('');
console.log('    # Check auth method');
console.log('    grep "getUserManagementInfo" server_logs.txt');

console.log('\n' + '='.repeat(80));
console.log('NEXT STEPS: Examine server.ts:927 to see which API client method is called');
console.log('='.repeat(80));