README.md

---
title: TravAI
emoji: 📊
colorFrom: green
colorTo: pink
sdk: gradio
sdk_version: 5.33.1
app_file: app.py
pinned: false
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference


# 🗺️ TravAI MCP Tool  
**Track**: `mcp-server-track`  
**Hackathon**: Agents & MCP Hackathon 2025  
**Team**: Sarthak Bhardwaj, Maria Dirnberger, Pulkit Thukral  

---

## 🌟 Overview  
**TravAI MCP Tool** is an agent accessible Gradio app that functions as a **Model Context Protocol (MCP) Server**. It helps users and by extension, AI agents plan smart travel routes and check localized weather forecasts for their trips.

This app includes:
- 🧭 **Google Maps Directions**: Get step-by-step, optimized routes between locations, optionally with waypoints, travel mode, and a static map snapshot.
- 🌤️ **Weather Forecast**: Get detailed weather insights (including hourly breakdowns and UV index) for a given location and date range, using the Open-Meteo API.

Perfect for itinerary building agents or AI assistants that need contextual, real world travel and weather data.

---

## 🚀 Live Demo  
👉 [Launch the MCP Tool on Hugging Face Spaces](https://huggingface.co/spaces/Agents-MCP-Hackathon/TravAI)  
🎥 [Watch a quick demo of the tool in action](https://www.youtube.com/watch?v=hUbLu7mppgM)

---

## 🔧 Features

### 📍 Google Maps Directions Tool  
**Inputs:**
- Source Location (text)
- Destination Location (text)
- Travel Mode (driving / walking / bicycling / transit)
- Departure Time (in `YYYY-MM-DD HH:MM` format)

**Output:**  
- Markdown summary of route with:
  - Total distance and duration
  - Step by step directions
  - Static map snapshot

---

### 🌦️ Weather Forecast Tool  
**Inputs:**
- Location Name
- Start Date
- End Date

**Output:**  
- Daily weather breakdown (sunrise, sunset, UV index, temperature)
- Hourly details (up to 7 days ahead): temperature, weather condition, UV index, visibility
- Markdown-formatted output

---

## 📜 How to Use (MCP-Compatible)

To use this tool via MCP, simply connect any MCP-compatible client such as:
- [Claude Desktop](https://huggingface.co/spaces/Anthropic/claude-desktop)
- [Cursor](https://www.cursor.so/)
- [Tiny Agents](https://huggingface.co/spaces/mcp/tiny-agents)

This app exposes two API endpoints:
- `/predict/get direction`
- `/predict/get weather forecast`

Agents can interact with it using structured input fields defined in the Gradio UI and receive Markdown or structured output to reason over.

---

## 💡 Motivation  
We wanted to build a travel-assistant-style MCP tool that an LLM agent could query in natural language to:
- Check if walking from Brandenburg Gate to Museum Island makes sense.
- See if it might rain in Paris during the second week of June.
- Create routes with coffee stops between meetings.

Combining **live navigation logic** with **real weather forecasting** creates powerful context for itinerary-focused AI agents.

---

## 🛠️ Tech Stack  
- `Gradio 4.x` (with `mcp_server=True`)
- `Google Maps Directions API`
- `Open-Meteo API`
- `geopy`, `pandas`, `dotenv`, `requests`, `re`, `datetime`, `json`

---

## 🔐 API Keys  
- Requires a valid `GOOGLE_API_KEY` in a `.env` file for route planning.
- Weather data is free and does not require a key (via Open-Meteo).

---

## 📥 Setup Instructions  

1. Clone this repo  
2. Create a `.env` file with your Google API key:
   ```dotenv
   GOOGLE_API_KEY=your_api_key_here
3. Install dependencies
    ```
    pip install -r requirements.txt
4. Run locally
    ```
    python app.py

---

## 🎯 Future Enhancements
- Auto-detect location from IP  
- Add alerts for UV index or rain warnings  
- Suggest alternate routes based on weather  
- Integrate with calendar events for smart trip planning  

---

## 📬 Contact

Built by **Sarthak Bhardwaj**, **Maria Dirnberger**, and **Pulkit Thukral**