Umbrella MCP Server

#!/usr/bin/env node /** * UMBRELLA CAUI API REQUIREMENTS EXPLANATION * =========================================== * This script explains what's needed to access the /invoices/caui endpoint */ const axios = require('axios'); // Color codes for terminal output const colors = { green: '\x1b[32m', red: '\x1b[31m', yellow: '\x1b[33m', blue: '\x1b[34m', cyan: '\x1b[36m', magenta: '\x1b[35m', reset: '\x1b[0m', bold: '\x1b[1m', underline: '\x1b[4m', dim: '\x1b[2m' }; console.log(` ${colors.cyan}${colors.bold}════════════════════════════════════════════════════════════════════════ UMBRELLA /invoices/caui API REQUIREMENTS ════════════════════════════════════════════════════════════════════════${colors.reset} `); console.log(`${colors.bold}${colors.underline}WHAT IS THE CAUI ENDPOINT?${colors.reset} The ${colors.yellow}/invoices/caui${colors.reset} endpoint is the main Cost and Usage API that provides: • Cloud provider costs (AWS, Azure, GCP) • Resource usage data • Cost breakdowns by service, region, account • Time-series cost data `); // SECTION 1: Required Headers console.log(`${colors.green}${colors.bold}1. REQUIRED HEADERS${colors.reset} ${colors.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset} ${colors.yellow}MANDATORY headers for every CAUI request:${colors.reset} ${colors.blue}Authorization:${colors.reset} Bearer <access_token> • Obtained from /authentication endpoint • Identifies WHO is making the request • Format: "Bearer xxx.yyy.zzz" ${colors.blue}apikey:${colors.reset} <context-specific-key> • Determines WHAT data you can access • Can be default, cloud-specific, or customer-specific • Examples: "default-key", "aws-context-key", "customer-encrypted-key" ${colors.blue}Content-Type:${colors.reset} application/json • Required for proper request parsing ${colors.blue}Accept:${colors.reset} application/json • Ensures JSON response format ${colors.dim}Example headers object:${colors.reset} { "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs...", "apikey": "8bd39ae4-ebea-4426-bd22-07349dd8b962", "Content-Type": "application/json", "Accept": "application/json" } `); // SECTION 2: Query Parameters console.log(`${colors.green}${colors.bold}2. QUERY PARAMETERS${colors.reset} ${colors.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset} ${colors.yellow}REQUIRED Parameters:${colors.reset} ${colors.blue}startDate${colors.reset} (YYYY-MM-DD) • Beginning of the date range • Example: "2025-01-01" ${colors.blue}endDate${colors.reset} (YYYY-MM-DD) • End of the date range • Example: "2025-01-31" ${colors.yellow}COMMON Optional Parameters:${colors.reset} ${colors.blue}periodGranLevel${colors.reset} • Granularity of the data • Values: "day", "week", "month", "year" • Default: "month" ${colors.blue}costType${colors.reset} • Type of cost to retrieve • Format: JSON array string '["cost"]' or '["usage"]' or '["cost","usage"]' • Default: '["cost"]' ${colors.blue}isUnblended${colors.reset} • Whether to use unblended costs • Values: true/false • Default: false ${colors.blue}groupBy${colors.reset} • How to group the results • Values: "none", "service", "region", "account", "cloudProvider" • Default: "none" ${colors.blue}cloudProvider${colors.reset} • Filter by cloud provider • Format: JSON array string '["aws"]' or '["azure"]' or '["gcp"]' • Example: '["aws","azure"]' ${colors.blue}filters${colors.reset} • Additional filters for the data • Format: Object with key-value pairs • Example: { "service": "AmazonEC2", "region": "us-east-1" } ${colors.blue}excludeFilters${colors.reset} • Exclude specific items • Format: Object with arrays • Example: { "chargetype": ["Tax", "Credit"] } `); // SECTION 3: Complete Request Examples console.log(`${colors.green}${colors.bold}3. COMPLETE REQUEST EXAMPLES${colors.reset} ${colors.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset} ${colors.yellow}Example 1: Basic Monthly AWS Costs${colors.reset} ${colors.magenta}GET https://api.umbrellacost.io/api/v1/invoices/caui${colors.reset} ${colors.blue}Headers:${colors.reset} { "Authorization": "Bearer <token>", "apikey": "<key>" } ${colors.blue}Query Parameters:${colors.reset} { "startDate": "2025-01-01", "endDate": "2025-01-31", "periodGranLevel": "month", "cloudProvider": '["aws"]', "costType": '["cost"]', "isUnblended": true } ${colors.yellow}Example 2: Daily Costs Grouped by Service${colors.reset} ${colors.magenta}GET https://api.umbrellacost.io/api/v1/invoices/caui${colors.reset} ${colors.blue}Query Parameters:${colors.reset} { "startDate": "2025-01-01", "endDate": "2025-01-07", "periodGranLevel": "day", "groupBy": "service", "costType": '["cost","usage"]' } ${colors.yellow}Example 3: Costs Excluding Tax and Credits${colors.reset} ${colors.magenta}GET https://api.umbrellacost.io/api/v1/invoices/caui${colors.reset} ${colors.blue}Query Parameters:${colors.reset} { "startDate": "2025-01-01", "endDate": "2025-01-31", "excludeFilters": { "chargetype": ["Tax", "Credit", "Refund"] } } ${colors.yellow}Example 4: Multi-Cloud Cost Comparison${colors.reset} ${colors.magenta}GET https://api.umbrellacost.io/api/v1/invoices/caui${colors.reset} ${colors.blue}Query Parameters:${colors.reset} { "startDate": "2025-01-01", "endDate": "2025-01-31", "cloudProvider": '["aws","azure","gcp"]', "groupBy": "cloudProvider", "periodGranLevel": "month" } `); // SECTION 4: Response Structure console.log(`${colors.green}${colors.bold}4. EXPECTED RESPONSE STRUCTURE${colors.reset} ${colors.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset} ${colors.yellow}Typical response fields:${colors.reset} ${colors.blue}totalCost${colors.reset} • Total cost for the period • Type: number ${colors.blue}currency${colors.reset} • Currency of the costs • Example: "USD" ${colors.blue}costs${colors.reset} • Array of cost data points • Each item contains: - period: Date/time period - cost: Cost amount - usage: Usage amount (if requested) - Additional groupBy fields ${colors.blue}services${colors.reset} (when groupBy="service") • Array of services with costs • Each item contains: - serviceName: Name of the service - cost: Service cost - percentage: % of total ${colors.dim}Example response structure:${colors.reset} { "totalCost": 15234.56, "currency": "USD", "costs": [ { "period": "2025-01-01", "cost": 15234.56, "cloudProvider": "aws" } ], "services": [ { "serviceName": "AmazonEC2", "cost": 8500.00, "percentage": 55.8 } ] } `); // SECTION 5: MSP Customer Access console.log(`${colors.green}${colors.bold}5. MSP CUSTOMER ACCESS (SPECIAL CASE)${colors.reset} ${colors.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset} ${colors.yellow}When accessing customer data as an MSP:${colors.reset} ${colors.blue}Additional Header Required:${colors.reset} ${colors.magenta}commonparams:${colors.reset} {"isPpApplied": true} • Indicates MSP customer context • Ensures proper data filtering ${colors.blue}Additional Parameters:${colors.reset} ${colors.magenta}customer_account_key:${colors.reset} "<customer-key>" • Identifies which customer's data to access • Used internally to build customer-specific apikey ${colors.magenta}customer_division_id:${colors.reset} "<division-id>" • Optional division identifier • For customers with multiple divisions ${colors.dim}Example MSP request:${colors.reset} Headers: { "Authorization": "Bearer <msp-token>", "apikey": "<encrypted-customer-key>", "commonparams": "{\\"isPpApplied\\":true}" } Parameters: { "startDate": "2025-01-01", "endDate": "2025-01-31", "customer_account_key": "customer123" } `); // SECTION 6: Common Errors console.log(`${colors.green}${colors.bold}6. COMMON ERRORS & SOLUTIONS${colors.reset} ${colors.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset} ${colors.red}401 Unauthorized${colors.reset} • Cause: Invalid or expired token • Solution: Re-authenticate to get new token ${colors.red}403 Forbidden${colors.reset} • Cause: Valid token but no access to requested data • Solution: Check apikey and permissions ${colors.red}400 Bad Request${colors.reset} • Cause: Invalid parameters or date format • Solution: Check date format (YYYY-MM-DD) and parameter syntax ${colors.red}"No data available"${colors.reset} • Cause: No costs in the specified period • Solution: Check date range and filters ${colors.red}"Invalid cloudProvider"${colors.reset} • Cause: Wrong format for cloudProvider parameter • Solution: Use JSON array format: '["aws"]' `); // Practical demonstration async function demonstrateCauiCall() { console.log(` ${colors.cyan}${colors.bold}════════════════════════════════════════════════════════════════════════ LIVE DEMONSTRATION ════════════════════════════════════════════════════════════════════════${colors.reset} `); const API_URL = 'https://api.umbrellacost.io/api/v1'; const credentials = { username: 'david+saola@umbrellacost.com', password: 'Dsamsung1!' }; console.log(`${colors.yellow}Step 1: Authenticating...${colors.reset}`); try { // Authenticate const authResponse = await axios.post(`${API_URL}/authentication`, credentials); if (authResponse.data && authResponse.data.access_token) { console.log(`${colors.green}✅ Authenticated successfully${colors.reset}`); const headers = { 'Authorization': `Bearer ${authResponse.data.access_token}`, 'apikey': authResponse.data.access_token, 'Content-Type': 'application/json', 'Accept': 'application/json' }; console.log(`\n${colors.yellow}Step 2: Calling CAUI endpoint...${colors.reset}`); console.log(`${colors.dim}Parameters: startDate=2025-01-01, endDate=2025-01-31, periodGranLevel=month${colors.reset}`); // Call CAUI endpoint const cauiResponse = await axios.get(`${API_URL}/invoices/caui`, { headers: headers, params: { startDate: '2025-01-01', endDate: '2025-01-31', periodGranLevel: 'month', costType: '["cost"]', isUnblended: true } }); console.log(`${colors.green}✅ CAUI call successful!${colors.reset}`); console.log(`${colors.blue}Response structure:${colors.reset}`); console.log(` - Total Cost: ${cauiResponse.data.totalCost || 'N/A'}`); console.log(` - Currency: ${cauiResponse.data.currency || 'N/A'}`); console.log(` - Data Points: ${cauiResponse.data.costs ? cauiResponse.data.costs.length : 0}`); } } catch (error) { if (error.response?.status === 401) { console.log(`${colors.red}❌ Authentication failed - Invalid credentials${colors.reset}`); } else if (error.response?.status === 403) { console.log(`${colors.red}❌ Access forbidden - Check permissions${colors.reset}`); } else { console.log(`${colors.red}❌ Error: ${error.message}${colors.reset}`); } } } // Summary console.log(` ${colors.cyan}${colors.bold}════════════════════════════════════════════════════════════════════════ SUMMARY ════════════════════════════════════════════════════════════════════════${colors.reset} ${colors.green}${colors.bold}MINIMUM REQUIREMENTS for CAUI API:${colors.reset} ${colors.yellow}1.${colors.reset} ${colors.bold}Authentication headers${colors.reset} (Authorization + apikey) ${colors.yellow}2.${colors.reset} ${colors.bold}Date range${colors.reset} (startDate + endDate in YYYY-MM-DD format) ${colors.yellow}3.${colors.reset} Valid ${colors.bold}authentication token${colors.reset} from /authentication endpoint ${colors.green}${colors.bold}RECOMMENDED PARAMETERS:${colors.reset} • ${colors.bold}periodGranLevel${colors.reset} - Set granularity (day/week/month) • ${colors.bold}costType${colors.reset} - Specify cost and/or usage data • ${colors.bold}isUnblended${colors.reset} - Use true for actual costs • ${colors.bold}groupBy${colors.reset} - Organize data by service/region/account • ${colors.bold}excludeFilters${colors.reset} - Remove tax, credits, refunds ${colors.cyan}The CAUI endpoint is the PRIMARY endpoint for cost data retrieval.${colors.reset} `); // Run demo if requested if (process.argv.includes('--demo')) { demonstrateCauiCall(); } else { console.log(`${colors.dim}Run with --demo flag to see a live API call demonstration${colors.reset}`); }