Trip Planner MCP PoC

This is a Proof of Concept for a Trip Planner application using the Model Context Protocol (MCP), Postgres, and Neo4j. It demonstrates how an Orchestrator Agent can coordinate with specialized agents (Team, Food, Travel) to answer complex queries.

Prerequisites

1. Docker Desktop: Ensure Docker is installed and running.
2. Python 3.10+: Ensure Python is installed.

Setup

1. Start the Databases: Open a terminal in this folder and run:

   docker-compose up -d
   

   This will start Postgres (port 5432) and Neo4j (ports 7474, 7687).

2. Create Virtual Environment:

   python -m venv venv
   # Windows
   venv\Scripts\activate
   # Mac/Linux
   # source venv/bin/activate
   

3. Install Dependencies:

   pip install -r requirements.txt
   

4. Configure Environment Variables: Copy .env.example to .env and add your API keys:

   # Windows
   copy .env.example .env
   # Mac/Linux
   # cp .env.example .env
   

   Edit .env and add:

   • GOOGLE_API_KEY: Get from https://makersuite.google.com/app/apikey
   • OPENWEATHER_API_KEY: Get from https://openweathermap.org/api (free tier)

5. Seed Neo4j Data: The Postgres data is seeded automatically. For Neo4j, run this script once:

   python src/db_utils.py
   

Running the Application

Option 1: Test Trip Recommendations Tool

Test the new trip recommendations tool with real-time weather data:

python test_trip_recommendations.py

Option 2: Orchestrator (Simulated)

Run the hardcoded orchestrator to see the agent workflow without an API key:

python src/orchestrator.py

Option 3: Chatbot (Single Agent)

Run the interactive chatbot (requires Google API Key):

1. Create a .env file in the root folder:

   GOOGLE_API_KEY=your-gemini-api-key
   OPENWEATHER_API_KEY=your-openweather-api-key
   

   Get free OpenWeather API key from: https://openweathermap.org/api (1000 calls/day free)

2. Run the chatbot:

   python src/chatbot.py
   

Option 4: A2A Chatbot (Multi-Agent System) ✨ RECOMMENDED

Run the advanced multi-agent system where an Orchestrator coordinates with specialized Team, Food, and Travel agents:

1. Ensure .env has your GOOGLE_API_KEY and OPENWEATHER_API_KEY.
2. Run the A2A chatbot:

   python src/a2a_chatbot.py
   

Features:

• 🤖 Intelligent Agent Orchestration: Automatically routes queries to specialized agents (Team, Food, Travel)
• 💬 Conversational Context: Maintains chat history across sessions (chat_history.json)
• 🔄 Parallel Processing: Multiple agents work together to provide comprehensive responses
• 🎯 Smart Query Understanding: Uses Gemini AI to analyze and decompose complex travel planning requests
• 🌐 Full MCP Integration: Seamless access to Neo4j, Postgres, Weather API, and Country Info API

The A2A chatbot is fully functional and provides the most advanced trip planning experience with multi-agent collaboration.

How it Works

Core Components

1. src/mcp_server.py: The MCP Server exposing multiple tools:

   • run_cypher_query: Execute raw Cypher queries against Neo4j (employee org graph).
   • run_sql_query: Execute raw SQL queries against Postgres (food preferences, trip data).
   • get_trip_recommendations: Get comprehensive travel recommendations with real-time weather data, customizable preferences, dates, group size, and budget.
   • get_country_info: Get country information (currency, languages) from RestCountries API.

2. src/orchestrator.py: Basic orchestrator with simulated agent workflow (no API key needed).

3. src/a2a_chatbot.py: Advanced Multi-Agent System ✨

   • Orchestrator Agent: Analyzes user queries and coordinates specialized agents
   • Team Agent: Handles employee data queries using Neo4j graph database
   • Food Agent: Manages food preferences and dietary requirements from Postgres
   • Travel Agent: Provides comprehensive trip planning with weather and location data
   • Intelligent Routing: Uses Gemini AI to determine which agents are needed for each query
   • Context Aware: Maintains conversation history and builds on previous interactions
   • Parallel Execution: Multiple agents can work simultaneously for complex queries

4. src/chatbot.py: Single-agent chatbot for basic interactions.

Project Structure

• docker-compose.yml: Database configuration.
• data/: Initialization scripts for databases.
• src/: Source code.
  • mcp_server.py: The MCP tool provider with database query tools.
  • orchestrator.py: Basic orchestrator with simulated workflow.
  • db_utils.py: Database connection helpers.
  • a2a_chatbot.py: Advanced multi-agent chatbot system ✨ (Fully functional)
  • chatbot.py: Single-agent chatbot for basic use.
• test_trip_recommendations.py: Test script for trip recommendations tool.
• TRIP_RECOMMENDATIONS_GUIDE.md: Comprehensive guide for using trip recommendations.
• ARCHITECTURE.md: Detailed system architecture documentation.
• AGENT_UPDATES.md: Agent implementation updates and changes.
• .env.example: Template for environment variables.

New Features

🌦️ Real-Time Weather Integration

The get_trip_recommendations tool now fetches live weather data from OpenWeatherMap API:

• Current conditions and 5-day forecast
• Temperature, humidity, wind speed
• Weather-based packing tips
• Automatic location geocoding

🎯 Smart Trip Planning

• Customizable Preferences: adventure, food, culture, relaxation, shopping, nature
• Group Travel Support: Tips for traveling with multiple people
• Budget-Aware: Recommendations based on budget constraints
• Date Flexibility: Auto-defaults to upcoming weekend if dates not specified
• External Resources: Links to TripAdvisor, Google Maps, Booking.com, WikiTravel

📊 Example Queries You Can Try (A2A Chatbot)

1. Basic Trip: "Plan a weekend trip to Paris"
2. Detailed Planning: "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"
3. Group Trip: "We are 8 friends planning a relaxation and shopping trip to Bali"
4. Team Outing: "Get my team members and plan a 3-day team outing to Goa considering everyone's food preferences"
5. Multi-Agent Query: "Who are the employees under Bob Chen and what are their food preferences? Plan a team dinner in San Francisco"
6. Complex Planning: "I want to organize a corporate retreat to Jaipur for 15 people next month with cultural activities"

🔧 Advanced Database Queries

• run_cypher_query: Execute raw Cypher queries for complex Neo4j graph traversals
• run_sql_query: Execute raw SQL queries for flexible Postgres data retrieval
• Full schema documentation in tool descriptions

For detailed usage instructions, see TRIP_RECOMMENDATIONS_GUIDE.md.