✈ TravelMind AI — Real-Time Agentic Travel Planner

A multi-agent AI travel planner powered by Google Serper API (live Google search) and an MCP Server (Model Context Protocol). Four specialized agents collaborate in a pipeline to produce a complete, real-time travel plan.

🤖 Agent Architecture

User Input
    │
    ▼
AgentOrchestrator
    │
    ├── Phase 1 ── SearchAgent ──────────────────── Google Serper API
    │               Fires 10 concurrent live searches:
    │               flights · hotels · attractions · weather · visa
    │               food · safety · budget · return flights · news
    │
    ├── Phase 2 (parallel) ──────────────────────────────────────────
    │   ├── PlanningAgent   — synthesises search results into travel info
    │   │                      (visa, safety, weather, attractions, news)
    │   └── BudgetAgent     — extracts real prices from Serper snippets,
    │                          builds full cost breakdown
    │
    └── Phase 3 ── ItineraryAgent ──────────────────────────────────
                   Builds day-by-day plan from live Serper places data
                   AI-generated (if Gemini key) or rule-based fallback

🔌 MCP Server

The MCP server exposes all agent tools as JSON-RPC 2.0 endpoints.

Endpoint	Method	Description
`/mcp`	POST	JSON-RPC 2.0 tool dispatcher
`/mcp/tools`	GET	List all 18 registered tools
`/mcp/health`	GET	Health check & status
`/mcp/events`	GET	SSE stream — real-time agent events

Registered Tools (18)

Tool	Description
`search_flights`	Live flight search between two cities
`search_hotels`	Hotels with live prices and ratings
`search_attractions`	Top tourist attractions at destination
`search_weather`	Current and forecast weather
`search_visa`	Visa requirements by nationality
`search_food`	Restaurants and dining options
`search_safety`	Travel safety advisories
`search_budget`	Daily cost and expense estimates
`general_search`	General Google search for any travel query
`search_trains`	Targeted train fares and duration search
`search_restaurants`	Targeted restaurant and cuisine search
`get_opening_hours`	Targeted attraction hours and ticket search
`get_travel_time`	Targeted route travel-time search
`calculate_budget`	Structured category budget calculation
`convert_currency`	Transparent caller-rate currency conversion
`plan_full_trip`	Run the full 4-agent pipeline, returns full plan
`get_itinerary`	Day-by-day itinerary from live data
`get_budget_breakdown`	Detailed budget calculation

🚀 Quick Start

1. Install

npm install

2. Configure

cp .env.example .env
# Edit .env — add your Serper API key (required for live data)

Get your free Serper API key at serper.dev — 2,500 free searches/month.

3. Run

# Interactive CLI planner
npm start

# MCP server only (for integrations)
npm run mcp

# Browser trip planner
# Start the MCP server, then open http://localhost:3001

# Run verification tests
npm run verify

🔑 API Keys

Key	Required?	Where to get	Free tier
`SERPER_API_KEY`	✅ Yes	serper.dev	2,500 searches/mo
`GEMINI_API_KEY`	❌ No	Google AI Studio	Free tier

Without Serper: App runs in estimation mode with built-in data.
Without Gemini: Uses rule-based itinerary and snippet extraction (fully functional).

📡 MCP Server API — Example Calls

Health check

curl http://localhost:3001/mcp/health

List tools

curl http://localhost:3001/mcp/tools

Call a tool (JSON-RPC 2.0)

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "search_flights",
      "arguments": {
        "origin": "New York",
        "destination": "Bangkok",
        "date": "2026-11-15"
      }
    }
  }'

Plan a full trip via MCP

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/call",
    "params": {
      "name": "plan_full_trip",
      "arguments": {
        "origin": "London",
        "destination": "Tokyo",
        "startDate": "2026-12-01",
        "endDate": "2026-12-10",
        "numTravelers": 2,
        "totalBudget": 5000,
        "currency": "USD",
        "budgetTier": "moderate",
        "travelType": "cultural",
        "nationality": "GB"
      }
    }
  }'

SSE event stream

curl -N http://localhost:3001/mcp/events

📁 Project Structure

Travel_planner_agent/
├── src/
│   ├── main.js                          # Entry point
│   ├── agents/
│   │   ├── SearchAgent.js               # Fires all Serper searches
│   │   ├── PlanningAgent.js             # Synthesises search → travel info
│   │   ├── RealtimeBudgetAgent.js       # Real-time price extraction & budget
│   │   ├── RealtimeItineraryAgent.js    # Day-by-day plan from live places
│   │   ├── BaseAgent.js                 # (shared base)
│   │   ├── TransportationAgent.js       # (legacy, used by fallback pipeline)
│   │   ├── AccommodationAgent.js
│   │   ├── BudgetAgent.js
│   │   ├── FoodAgent.js
│   │   └── ItineraryAgent.js
│   ├── core/
│   │   ├── AgentOrchestrator.js         # Real-time 3-phase coordinator
│   │   ├── PlannerOrchestrator.js       # (legacy offline orchestrator)
│   │   ├── config.js
│   │   └── constants.js
│   ├── mcp/
│   │   ├── mcpServer.js                 # MCP JSON-RPC 2.0 server (Express)
│   │   ├── mcpClient.js                 # MCP client with convenience wrappers
│   │   └── startServer.js              # Standalone server entry point
│   ├── realtime/
│   │   └── serperClient.js              # Google Serper API wrapper
│   ├── models/
│   │   └── TravelPlan.js                # Shared data model
│   ├── ui/
│   │   ├── realtimeApp.js               # Real-time app loop
│   │   ├── realtimeDisplay.js           # Terminal rendering (live-aware)
│   │   ├── realtimePrompts.js           # Inquirer prompts
│   │   ├── app.js                       # (legacy UI)
│   │   ├── display.js
│   │   └── prompts.js
│   ├── data/
│   │   ├── destinationData.js           # Curated city data (fallback)
│   │   └── visaRules.js
│   └── utils/
│       ├── logger.js
│       ├── helpers.js
│       ├── openaiClient.js
│       ├── geoClient.js
│       └── weatherClient.js
├── scripts/
│   └── verify.js                        # End-to-end test suite
├── plans/                               # Saved JSON trip plans (auto-created)
├── .env.example
├── package.json
└── README.md

✅ What's Live vs Estimated

Feature	With Serper key	Without Serper key
Flight prices	✅ Live Google search	⚡ Distance-based estimate
Hotel prices & names	✅ Live + ratings	⚡ Tier-based estimate
Attractions	✅ Live places + ratings	⚡ Built-in city data
Weather	✅ Live forecast	⚡ Open-Meteo API (free)
Visa info	✅ Live Google search	⚡ Local rules database
Restaurant names	✅ Live places	⚡ Built-in city data
Safety info	✅ Live advisories	⚡ Local curated data
Daily cost estimates	✅ Live cost pages	⚡ Tier-based defaults
Itinerary	✅ AI+live places / rule-based+live	⚡ Rule-based built-in

🛠 Requirements

Node.js 18+
npm