# ✈ 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
```bash
npm install
```

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

Get your **free** Serper API key at [serper.dev](https://serper.dev) — 2,500 free searches/month.

### 3. Run

```bash
# 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](https://serper.dev)| 2,500 searches/mo |
| `GEMINI_API_KEY`   | ❌ No     | [Google AI Studio](https://aistudio.google.com/apikey) | 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
```bash
curl http://localhost:3001/mcp/health
```

### List tools
```bash
curl http://localhost:3001/mcp/tools
```

### Call a tool (JSON-RPC 2.0)
```bash
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
```bash
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
```bash
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