# Travel Planner MCP Server

A multi-agent travel planning system built with [Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/) that exposes its tools via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).

The system uses a **root agent** with two **sub-agents** — a weather agent and a travel plan agent — to create weather-aware 3-day travel itineraries. The tools are also exposed through an MCP server, making them accessible to any MCP-compliant client.

## Architecture

```
┌─────────────────────────────────────────────────┐
│                  Root Agent                      │
│            (travel_planner)                      │
│                                                  │
│  Orchestrates the travel planning workflow:      │
│  gather info → check weather → create plan       │
│                                                  │
│  ┌─────────────────┐  ┌──────────────────────┐  │
│  │  Weather Agent   │  │  Travel Plan Agent   │  │
│  │                  │  │                      │  │
│  │  get_weather()   │  │  create_travel_plan()│  │
│  │  (Open-Meteo API)│  │  (itinerary builder) │  │
│  └─────────────────┘  └──────────────────────┘  │
└─────────────────────────────────────────────────┘

                    ▼ exposed via ▼

┌─────────────────────────────────────────────────┐
│              MCP Server (stdio)                  │
│                                                  │
│  Wraps ADK FunctionTools and exposes them as     │
│  MCP tools accessible to any MCP client          │
│                                                  │
│  Tools: get_weather, create_travel_plan          │
└─────────────────────────────────────────────────┘
```

## Project Structure

```
travel-planner-mcp-server/
├── travel_planner/              # ADK multi-agent package
│   ├── __init__.py
│   ├── agent.py                 # Root agent (orchestrator with sub-agents)
│   ├── sub_agents/
│   │   ├── __init__.py
│   │   ├── weather_agent.py     # Weather specialist sub-agent
│   │   └── travel_plan_agent.py # Travel planning specialist sub-agent
│   └── tools/
│       ├── __init__.py
│       ├── weather_tools.py     # Open-Meteo API weather tool
│       └── travel_tools.py      # Travel plan generation tool
├── mcp_server.py                # MCP server exposing ADK tools
├── adk_client_agent/            # Example ADK agent consuming the MCP server
│   └── mcp_travel_client/
│       ├── __init__.py
│       └── agent.py
├── pyproject.toml
├── requirements.txt
├── .env.example
└── README.md
```

## Prerequisites

- Python 3.10+
- A Google API key (for Gemini model access)

## Setup

1. **Clone the repository:**

   ```bash
   git clone <repo-url>
   cd travel-planner-mcp-server
   ```

2. **Install dependencies:**

   ```bash
   pip install -r requirements.txt
   ```

3. **Configure environment:**

   ```bash
   cp .env.example .env
   # Edit .env and add your Google API key
   ```

## Usage

### Option 1: Run the ADK Multi-Agent System Directly

This uses the root agent with its sub-agents through the ADK web UI:

```bash
adk web
# Select "travel_planner" in the browser UI
```

The root agent will:
1. Ask for your destination and travel date
2. Delegate to the **weather agent** to fetch the forecast
3. Delegate to the **travel plan agent** to create the itinerary
4. Present a comprehensive 3-day travel plan

### Option 2: Run the MCP Server

This exposes the tools via MCP protocol for any MCP client to consume:

```bash
python mcp_server.py
```

The MCP server exposes two tools:
- **`get_weather`** — Fetches 3-day weather forecast for a location using Open-Meteo API
- **`create_travel_plan`** — Generates a structured 3-day travel itinerary template

### Option 3: Run the MCP Client Agent

This demonstrates an ADK agent consuming the MCP server:

```bash
cd adk_client_agent
adk web
# Select "mcp_travel_client" in the browser UI
```

### Option 4: Connect from Any MCP Client

Add to your MCP client configuration (e.g., Claude Desktop, Cursor, etc.):

```json
{
  "mcpServers": {
    "travel-planner": {
      "command": "python3",
      "args": ["/path/to/mcp_server.py"]
    }
  }
}
```

## Tools

### `get_weather`

Fetches a 3-day weather forecast using the [Open-Meteo API](https://open-meteo.com/) (free, no API key required).

**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `location` | string | City or place name (e.g., "Paris", "Tokyo") |
| `date` | string | Start date in YYYY-MM-DD format |

**Returns:** Temperature (C/F), conditions, precipitation, wind speed, and UV index for 3 days.

### `create_travel_plan`

Generates a structured 3-day travel itinerary template.

**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `location` | string | Destination city or place |
| `start_date` | string | Trip start date (YYYY-MM-DD) |
| `weather_summary` | string | Weather conditions summary |
| `interests` | string | Travel interests (default: "general sightseeing") |

**Returns:** Day-by-day itinerary structure with time slots, meals, and tips.

## How It Works

This project demonstrates **Pattern 2** from the ADK documentation: [Building an MCP server with ADK tools](https://google.github.io/adk-docs/tools-custom/mcp-tools/#2-building-an-mcp-server-with-adk-tools-mcp-server-exposing-adk).

1. ADK `FunctionTool` wraps the Python tool functions
2. `adk_to_mcp_tool_type()` converts ADK tool schemas to MCP format
3. The MCP server advertises tools via `list_tools` and executes them via `call_tool`
4. Any MCP client can discover and invoke the tools through the standard protocol

## License

MIT