Trip Planner MCP

# Trip Recommendations Tool - User Guide ## Overview The `get_trip_recommendations` tool provides comprehensive, real-time travel planning assistance using actual weather data and intelligent recommendations based on your preferences. ## Features ✅ **Real-time Weather Data**: Fetches live weather forecasts from OpenWeatherMap API ✅ **Customizable Preferences**: Supports adventure, food, culture, relaxation, shopping, nature ✅ **Group Travel Support**: Considers number of travelers for tailored recommendations ✅ **Budget-Aware**: Provides tips based on your budget constraints ✅ **Date-Flexible**: Works with specific dates or defaults to upcoming weekend ✅ **External Resources**: Provides links to TripAdvisor, Google Maps, Booking.com, etc. ## Setup ### 1. Get OpenWeather API Key (Free) 1. Visit: https://openweathermap.org/api 2. Sign up for a free account 3. Generate an API key (Free tier: 1,000 calls/day) 4. Add to your `.env` file: ``` OPENWEATHER_API_KEY=your_api_key_here ``` ### 2. Restart MCP Server After adding the API key, restart your chatbot or MCP server to load the environment variable. ## Usage Examples ### Example 1: Basic Trip (Minimal Input) **Query**: "Plan a trip to Paris" **What happens**: - Location: Paris - Dates: Upcoming weekend (auto-calculated) - People: 1 person - Preferences: Default (sightseeing, culture, food) - Weather: Real-time forecast fetched - Budget: Not specified **Output includes**: - 5-day weather forecast - Sightseeing & culture recommendations - Food & culture suggestions - Useful resource links --- ### Example 2: Detailed Trip Planning **Query**: "Plan a 5-day adventure trip to Udaipur from 2025-12-20 to 2025-12-25 for 4 people with preferences: adventure, nature, food. Budget is 5000 INR per person" **Parameters**: - `location`: "Udaipur" - `start_date`: "2025-12-20" - `end_date`: "2025-12-25" - `num_people`: 4 - `preferences`: "adventure, nature, food" - `budget_per_person`: 5000 **Output includes**: - Trip duration calculation (5 days) - Real-time weather forecast for December - Adventure & Nature recommendations - Food & Culture suggestions - Group travel tips (4 people) - Budget-conscious recommendations - Weather-based packing tips - External resource links --- ### Example 3: Group Trip with Specific Interests **Query**: "We are 8 friends planning a relaxation and shopping trip to Bali for 7 days starting Jan 15, 2026" **Parameters**: - `location`: "Bali" - `start_date`: "2026-01-15" - `end_date`: "2026-01-22" - `num_people`: 8 - `preferences`: "relaxation, shopping" **Output includes**: - Weather forecast for January in Bali - Relaxation recommendations (spas, beaches) - Shopping suggestions (local markets) - Group accommodation tips - Group transportation advice - External booking resources --- ## Supported Preferences | Preference | Recommendations Include | |------------|------------------------| | `adventure` | Hiking trails, adventure sports, outdoor activities, gear suggestions | | `nature` | Nature trails, parks, outdoor exploration, wildlife | | `food` | Local restaurants, street food, food tours, markets | | `culture` | Museums, historical sites, guided tours, cultural experiences | | `sightseeing` | Popular attractions, skip-the-line tickets, must-see places | | `relaxation` | Spas, wellness centers, peaceful locations, downtime tips | | `shopping` | Markets, shopping districts, souvenirs, tax refunds | **Mix and match**: You can combine multiple preferences, e.g., "adventure, food, culture" --- ## Real-Time Weather Integration The tool fetches: - **Temperature**: Current and feels-like temperature in Celsius - **Weather Conditions**: Clear, cloudy, rain, snow, etc. - **Humidity**: Percentage - **Wind Speed**: Meters per second - **Forecast**: Up to 24 hours ahead (8 data points at 3-hour intervals) **Weather-based tips automatically added**: - Rain forecasted → Pack rain gear, plan indoor activities - Hot weather (>30°C) → Stay hydrated, use sun protection - Cold weather (<10°C) → Pack warm clothing --- ## Output Structure ```json { "location": "Paris", "trip_details": { "start_date": "2025-11-29", "end_date": "2025-12-01", "duration_days": 3, "num_people": 2, "preferences": ["culture", "food", "sightseeing"], "budget_per_person": 10000 }, "weather_forecast": { "location": "Paris, FR", "coordinates": {"lat": 48.8566, "lon": 2.3522}, "forecasts": [ { "datetime": "2025-11-29 12:00:00", "temp": "12°C", "feels_like": "10°C", "weather": "light rain", "humidity": "85%", "wind_speed": "3.5 m/s" } // ... more forecasts ], "summary": "Weather in Paris: light rain, 12°C" }, "recommendations": [ { "category": "Getting Started", "suggestions": [...] }, { "category": "Food & Culture", "suggestions": [...] } ], "tips": [ "Pack rain gear and plan indoor activities", "Traveling with 2 people - consider group discounts" ], "useful_resources": { "weather": "https://openweathermap.org/city/Paris", "tripadvisor": "https://www.tripadvisor.com/Search?q=Paris", "google_maps": "https://www.google.com/maps/search/?api=1&query=Paris", "booking": "https://www.booking.com/searchresults.html?ss=Paris", "wikitravel": "https://wikitravel.org/en/Paris" } } ``` --- ## Using with Employee Data The tool can integrate with your Neo4j employee graph to plan trips based on team relationships: **Example Query**: "I want to plan a team outing to Goa for my team. Get my team members and their food preferences, then plan a 3-day trip" **The agent will**: 1. Use `run_cypher_query` to find your team members 2. Use `run_sql_query` to get their food preferences and dietary restrictions 3. Use `get_trip_recommendations` with appropriate preferences 4. Consider group size and dietary needs 5. Suggest venues from the database that match team preferences --- ## Troubleshooting ### "Weather data unavailable" Error **Cause**: `OPENWEATHER_API_KEY` not set in environment **Solution**: 1. Get API key from https://openweathermap.org/api 2. Add to `.env` file: `OPENWEATHER_API_KEY=your_key` 3. Restart MCP server/chatbot ### "Could not find location" Error **Cause**: Location name not recognized by geocoding API **Solution**: - Use more specific location name (e.g., "Paris, France" instead of just "Paris") - Check spelling - Try adding country name ### API Rate Limit Exceeded **Cause**: Free tier limit (1,000 calls/day) exceeded **Solution**: - Wait until next day for reset - Consider upgrading OpenWeather plan - Cache weather data for frequently queried locations --- ## Future Enhancements Potential additions to the tool: - ✨ Integration with TripAdvisor API for real attraction data - ✨ Google Places API for restaurant recommendations - ✨ Flight price tracking APIs - ✨ Hotel booking integration - ✨ Event and festival calendars - ✨ COVID-19 travel restrictions data - ✨ Currency exchange rates - ✨ Local transportation options --- ## Tips for Best Results 1. **Be Specific**: Provide as many details as possible (dates, preferences, budget) 2. **Use Correct Date Format**: Always use YYYY-MM-DD format 3. **List Multiple Preferences**: Comma-separated works best 4. **Consider Group Size**: Accurate count helps with tailored recommendations 5. **Set Realistic Budgets**: Helps filter appropriate suggestions 6. **Check Weather First**: Plan activities around forecast 7. **Use External Links**: Click through to resources for detailed information --- ## Example Conversational Queries ✅ "Plan a weekend trip to Mumbai for 2 people who love food and shopping" ✅ "I need a 10-day adventure trip to Nepal starting March 1st for a group of 6" ✅ "What's the weather like in Dubai next week? Plan a relaxation trip" ✅ "Budget trip to Jaipur for 3 days with 4 friends, budget 3000 per person" ✅ "Plan a family trip to Singapore with culture and nature activities" --- **Pro Tip**: Combine this tool with the employee data tools for intelligent team trip planning that considers everyone's preferences and dietary restrictions!