# Weather MCP Server & Databricks Agent

A Model Context Protocol (MCP) server built with **FastMCP** exposing weather intelligence tools backed by the **Open-Meteo** API, integrated with **Databricks Agent Bricks**.

---

## 📁 Repository Structure

```
weather-mcp/
├── src/
│   └── weather_mcp/
│       ├── __init__.py          # Package exports
│       ├── weather_broker.py    # Adapter module & WeatherClient / WeatherRuleEngine
│       └── mcp_server.py        # FastMCP server & tool definitions
├── tests/
│   └── test_weather.py          # Unit & integration test suite
├── AGENT_PROMPT.md              # Databricks Agent system prompt & registration guide
├── CONTEXT.md                   # Domain model glossary
├── README.md                    # Project documentation
├── app.yaml                     # Databricks Apps manifest
├── pyproject.toml               # Python package configuration
└── requirements.txt             # Production dependencies
```

---

## 🏛️ Architecture Overview

```
 ┌────────────────────────────────────────────────────────┐
 │            Databricks Agent Bricks Agent               │
 └──────────────────────────┬─────────────────────────────┘
                            │ Model Context Protocol (MCP / HTTP)
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │      FastMCP Server (src/weather_mcp/mcp_server.py)    │
 └──────────────────────────┬─────────────────────────────┘
                            │ Thin wrapper calls
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │     Broker Adapter (src/weather_mcp/weather_broker.py) │
 └──────────┬─────────────────────────────────┬───────────┘
            │ Geocoding API                   │ Forecast API
            ▼                                 ▼
 ┌──────────────────────┐         ┌───────────────────────┐
 │ Open-Meteo Geocoding │         │  Open-Meteo Forecast  │
 └──────────────────────┘         └───────────────────────┘
```

---

## 🛠️ MCP Tools Reference

| Tool Signature | Description | Key Arguments |
| :--- | :--- | :--- |
| `get_current_weather` | Returns real-time temperature, humidity, wind speed, and conditions. | `location: str` |
| `get_forecast` | Multi-day daily forecast (high/low temps, precipitation %, conditions). | `location: str`, `days: int = 3` |
| `predict_umbrella_needed` | Evaluates if an umbrella is needed based on precip probability (>=40%) and volume. | `location: str`, `date: str = "today"` |
| `get_travel_recommendation` | Generates clothing packing advice and outdoor activity ratings. | `location: str`, `days: int = 3` |
| `compare_city_weather` | Compares current weather conditions across multiple cities. | `cities: str` (comma-separated) |

---

## 🚀 Setup & Local Execution

### 1. Install Dependencies
```bash
uv sync
```

### 2. Run Test Suite
```bash
PYTHONPATH=src uv run python tests/test_weather.py
```

### 3. Start FastMCP Server Locally
```bash
uv run fastmcp run src/weather_mcp/mcp_server.py --transport http --port 8000
```
The server will listen at `http://127.0.0.1:8000/mcp`.

---

## ☁️ Databricks Apps Deployment & Agent Bricks Registration

1. **Deploy App**:
   Deploy this repository to Databricks Apps using `app.yaml`:
   ```yaml
   command:
     - "fastmcp"
     - "run"
     - "src/weather_mcp/mcp_server.py"
     - "--transport"
     - "http"
     - "--host"
     - "0.0.0.0"
     - "--port"
     - "8000"
   ```

2. **Register External MCP Tool**:
   - In Databricks Workspace -> AI Playground / Agent Bricks.
   - Click **Add Tool -> External MCP Server**.
   - Enter App URL: `https://<databricks-app-url>/mcp`.

3. **Configure System Prompt**:
   - Copy system prompt from [AGENT_PROMPT.md](./AGENT_PROMPT.md).

---

## 🧪 Demonstrated Agent Queries & Responses

### Query 1: Rain & Umbrella Prediction
**User**: *"Will it rain in Chicago tomorrow?"*

- **Tool Call**: `predict_umbrella_needed(location="Chicago", date="tomorrow")`
- **Agent Response**:
  > "No, it is very unlikely to rain in Chicago tomorrow (2026-08-09). The precipitation probability is only **2%** with clear skies. High: **79.0°F (26.1°C)**, Low: **64.5°F (18.1°C)**. You won't need an umbrella!"

![Will it rain in Chicago tomorrow?](./Will%20it%20rain%20in%20Chicago%20tomorrow%3F.png)

### Query 2: Travel Packing Advice
**User**: *"Should I bring a jacket to Austin this weekend?"*

- **Tool Call**: `get_travel_recommendation(location="Austin, TX", days=3)`
- **Agent Response**:
  > "You will **not** need a heavy jacket in Austin this weekend! Temperatures will be very warm with highs reaching **99.6°F (37.5°C)** and lows around **76.1°F (24.5°C)**. I recommend packing light summer clothing and staying hydrated."

![Should I bring a jacket to Austin this weekend?](./Should%20I%20bring%20a%20jacket%20to%20Austin%20this%20weekend%3F.png)

### Query 3: Multi-City Weather Comparison
**User**: *"Is it warmer right now in Chicago, Austin, or Tokyo?"*

- **Tool Call**: `compare_city_weather(cities="Chicago, Austin, Tokyo")`
- **Agent Response**:
  > "Currently, **Austin, Texas** is the warmest at **96.6°F (35.9°C)**.
  > Comparison:
  > 1. **Austin, TX**: 96.6°F (35.9°C)
  > 2. **Chicago, IL**: 79.0°F (26.1°C)
  > 3. **Tokyo, Japan**: 73.9°F (23.3°C)"

![Is it warmer right now in Chicago, Austin, or Tokyo?](./Is%20it%20warmer%20right%20now%20in%20Chicago%2C%20Austin%2C%20or%20Tokyo%3F.png)

### Query 4: Edge Case Error Handling
**User**: *"What's the weather in NonExistentCityXYZ?"*

- **Tool Call**: `get_current_weather(location="NonExistentCityXYZ")`
- **Agent Response**:
  > "I couldn't find a location matching **'NonExistentCityXYZ'**. Could you please check the spelling or provide the city name alongside its state or country?"