Hostaway MCP Server

# Calculated Financial Reports - Implementation Summary ## Problem The Hostaway `/financialReports` API endpoint is not available for your account (returns 404). This is likely due to: - Account tier limitations (premium/enterprise feature) - Feature not enabled in Hostaway dashboard - API version mismatch ## Solution Implemented a **calculated fallback system** that computes financial reports from reservation data when the native Hostaway API is unavailable. ## How It Works ### 1. Automatic Fallback When the financial endpoint is called: 1. **First**: Try native Hostaway `/financialReports` API 2. **If 404**: Automatically fall back to calculated reports from reservations 3. **If other error**: Return appropriate error with correlation ID ### 2. Data Fetching (Context Window Protection) ```python # Fetch up to 1000 reservations in batches of 200 for offset in range(0, 1000, 200): batch = await client.search_bookings(limit=200, offset=offset) all_reservations.extend(batch) if len(batch) < 200: break # Last page ``` **Protection Mechanisms**: - Maximum 1000 reservations per request - Batch fetching (200 at a time) - Only returns aggregated summaries (not full reservation details) - Filters by date range to minimize data ### 3. Financial Calculation **From Reservation Data**: ```python # Revenue total_revenue = sum(totalPrice) cleaning_fees = sum(cleaningFee) taxes = sum(taxAmount) # Expenses channel_commissions = sum(channelCommissionAmount) hostaway_commissions = sum(hostawayCommissionAmount) total_expenses = channel_commissions + hostaway_commissions # Profitability net_income = total_revenue - total_expenses profit_margin = (net_income / total_revenue) * 100 # Metrics total_bookings = count(reservations) total_nights = sum(nights) average_daily_rate = total_revenue / total_nights average_booking_value = total_revenue / total_bookings ``` **Filters Applied**: - Date range: Overlap with report period (arrivalDate to departureDate) - Status: Excludes cancelled, declined, pending, inquiry bookings - Only confirmed revenue bookings included ### 4. Revenue by Channel Breaks down revenue by booking source: - `airbnbOfficial` - Airbnb bookings - `vrbo` - VRBO bookings - `direct` - Direct bookings - etc. ## Example Response ```json { "period": { "startDate": "2025-10-01", "endDate": "2025-10-31" }, "currency": "IDR", "revenue": { "totalRevenue": 118212671.4, "cleaningFees": 1100000.0, "taxes": 0.0, "byChannel": { "airbnbOfficial": 118212671.4 } }, "expenses": { "totalExpenses": 0.0, "channelCommissions": 0.0, "hostawayCommissions": 0.0 }, "profitability": { "netIncome": 118212671.4, "profitMargin": 100.0 }, "metrics": { "totalBookings": 4, "totalNights": 40, "averageDailyRate": 2955316.78, "averageBookingValue": 29553167.85 }, "dataSource": "calculated_from_reservations", "note": "This report is calculated from reservation data as the Hostaway financial reports API is not available for your account." } ``` ## Files Created 1. **src/services/financial_calculator.py** - `FinancialCalculator` class - `calculate_financial_report()` - Aggregate reports - `calculate_property_financials()` - Property-specific reports 2. **src/api/routes/financial.py** (Modified) - Added `_calculate_financial_report()` helper function - Updated exception handling for automatic fallback - Removed duplicate exception handlers 3. **deploy-to-hostinger-secure.sh** (Fixed) - Corrected deployment path to `/opt/hostaway-mcp` - Updated to use `docker-compose.prod.yml` ## Limitations **Data Availability**: - Commission data may be `null` in reservations (resulting in $0 expenses) - Tax data may be `null` - Security deposit data may be `null` **Context Window**: - Limited to 1000 reservations per request - If you have more bookings, older ones won't be included in calculations - Recommend filtering by date range (1-3 months at a time) ## Usage ### Via API ```bash # Get financial report for date range curl -H "X-API-Key: YOUR_API_KEY" \ "http://72.60.233.157:8080/api/financialReports?start_date=2025-10-01&end_date=2025-10-31" # Get property-specific report curl -H "X-API-Key: YOUR_API_KEY" \ "http://72.60.233.157:8080/api/financialReports?start_date=2025-10-01&end_date=2025-10-31&listing_id=400569" ``` ### Via Test Agent ```bash uv run python test_api_agent.py ``` ## Benefits ✅ **No Account Upgrade Required**: Works with your current Hostaway account ✅ **Transparent**: Includes note explaining data source ✅ **Accurate**: Calculated from actual reservation data ✅ **Context Window Safe**: Limits data fetching and returns aggregated summaries ✅ **Automatic**: Seamless fallback, no code changes needed for users ## Production Status - ✅ Deployed to http://72.60.233.157:8080 - ✅ Tested with test_api_agent.py - ✅ Working with real reservation data - ✅ Context window protection enabled --- **Status**: ✅ Production Ready **Last Updated**: 2025-10-19 **Implemented By**: Claude Code