# 🌤️ MCP Weather Agent

[![Python 3.13+](https://img.shields.io/badge/Python-3.13%2B-blue?style=flat-square)](https://www.python.org/)
[![OpenAI](https://img.shields.io/badge/OpenAI-GPT--4o--mini-brightgreen?style=flat-square)](https://openai.com/)
[![MCP](https://img.shields.io/badge/MCP-1.27%2B-orange?style=flat-square)](https://modelcontextprotocol.io/)
[![Playwright](https://img.shields.io/badge/Playwright-Browser%20Automation-9c27b0?style=flat-square)](https://playwright.dev/)

An intelligent, multi-region weather assistant powered by **OpenAI** and the **Model Context Protocol (MCP)**. 

Get real-time weather forecasts and alerts for **Israel** and the **United States** through a natural language chat interface. The agent intelligently routes questions to the appropriate data source and compiles answers from live web data and official weather APIs.

---

## ✨ Features

- 🤖 **AI-Powered Chat**: Conversational weather queries using GPT-4o-mini
- 🌍 **Dual Data Sources**:
  - 🇮🇱 **Israel**: Live web scraping from Weather2day via Playwright
  - 🇺🇸 **USA**: Official National Weather Service API
- 🔄 **Smart Tool Routing**: The agent automatically selects the right tool based on your question
- 💬 **Natural Language**: Ask questions in plain English; the agent understands context and intent
- 🔐 **Secure**: API keys stored in `.env` and excluded from version control
- 🎯 **Interactive**: Real-time chat loop with visible browser automation for Israel queries

---

## 📋 Table of Contents

- [Quick Start](#-quick-start)
- [Requirements](#-requirements)
- [Setup](#-setup)
- [Running the Agent](#-running-the-agent)
- [Architecture](#-architecture)
- [Example Queries](#-example-queries)
- [Troubleshooting](#-troubleshooting)
- [FAQ](#-faq)
- [Security](#-security)

---

## 🚀 Quick Start

Get up and running in 3 minutes:

```powershell
# 1. Install dependencies
uv sync
uv run playwright install chromium

# 2. Create .env file with your OpenAI API key
copy .env.example .env
# Edit .env and add: OPENAI_API_KEY=sk-...

# 3. Run the agent
uv run .\host.py

# 4. Ask a weather question!
# Example: "What is the weather forecast for Jerusalem?"
```

---

## 📦 Requirements

| Component | Version | Purpose |
|-----------|---------|---------|
| **Python** | 3.13+ | Runtime environment |
| **OpenAI API Key** | — | GPT-4o-mini model access |
| **uv** | Latest | Fast Python package manager |
| **Chromium** | Latest | Browser automation (Playwright) |
| **Internet** | — | API access and web scraping |

---

## 🔧 Setup

### 1. Install Dependencies

Open a terminal in the project directory and run:

```powershell
# Install Python dependencies
uv sync

# Download Chromium browser for Playwright (required for Israel weather)
uv run playwright install chromium
```

**First time taking a while?** Yes—Playwright downloads Chromium (~300 MB). This is a one-time operation.

### 2. Configure OpenAI API Key

Create a `.env` file in the project root:

```bash
# Option A: Copy the template
copy .env.example .env

# Option B: Create manually
echo OPENAI_API_KEY=your_openai_api_key > .env
```

Replace `your_openai_api_key` with your actual OpenAI API key from [platform.openai.com/account/api-keys](https://platform.openai.com/account/api-keys).

**⚠️ Important**: Never commit `.env` or share your API key. The `.gitignore` already excludes it.

### 3. Verify Installation

Test the setup:

```powershell
uv run .\host.py
```

You should see:
```
Connected to server with tools: [...]

MCP Client Started!
Type your queries or 'quit' to exit.

Query:
```

Press `Ctrl+C` or type `quit` to exit.

---

## ▶️ Running the Agent

Start the interactive chat:

```powershell
uv run .\host.py
```

The agent launches in interactive mode. Type a weather question and press Enter. The agent will:

1. ✅ Parse your question
2. 🔍 Route to the appropriate weather tool (Israel or USA)
3. 🌐 Fetch real-time data (may open a browser window for Israel)
4. 📊 Process and format the response
5. 💬 Return the answer

Type `quit` to exit.

**For Israel queries**: A Chromium browser window opens automatically. This is normal—the agent is using Playwright to interact with Weather2day. The window closes when the query completes.

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        OpenAI (GPT-4o-mini)                     │
│                      (Tool Selection & Reasoning)               │
└────────────────────────────┬────────────────────────────────────┘
                             │
                ┌────────────┴────────────┐
                │                         │
        ┌───────▼────────┐       ┌───────▼────────┐
        │  MCP Host      │       │   MCP Host     │
        │  (client.py)   │       │   (client.py)  │
        └───────┬────────┘       └───────┬────────┘
                │                         │
        ┌───────▼──────────────┐  ┌──────▼─────────────┐
        │ weather_Israel.py    │  │ weather_USA.py    │
        │ (Playwright + Web)   │  │ (NWS API)         │
        └───────┬──────────────┘  └──────┬─────────────┘
                │                         │
        ┌───────▼──────────────┐  ┌──────▼─────────────┐
        │   Weather2day.co.il  │  │    api.weather.gov│
        │  (Live Web Browser)  │  │   (REST API)      │
        └──────────────────────┘  └───────────────────┘
```

**Data Flow**:
1. You ask a question in the chat
2. The host sends it to OpenAI with available tools
3. OpenAI selects which tool to call based on the question
4. The appropriate MCP server executes and returns data
5. The host formats and returns the answer

---

## 💬 Example Queries

### 🇮🇱 Israel Weather

```
What is the weather forecast for Jerusalem?
Give me the forecast for Tel Aviv.
What is the weather like in Haifa today?
Show me the forecast for Eilat.
What is the weather in Beer Sheva?
Is it going to rain in Kfar Saba tomorrow?
Tell me about the weather in Nazareth.
What's the forecast for Tiberias?
```

**Supported Cities**: Jerusalem, Tel Aviv, Haifa, Eilat, Beer Sheva, Kfar Saba, Tiberias, Nazareth, and most major Israeli cities recognized by Weather2day.

### 🇺🇸 USA Weather

```
What is the weather forecast for New York City? (40.7128, -74.0060)
What's the weather at latitude 34.0522, longitude -118.2437? (Los Angeles)
Are there any active weather alerts in California?
What weather alerts are in effect in New York?
Give me the forecast for Chicago coordinates. (41.8781, -87.6298)
Are there any severe weather warnings in Texas?
```

**Format**:
- **Forecasts**: Use latitude/longitude coordinates
- **Alerts**: Use two-letter state codes (`CA`, `NY`, `TX`, etc.)

### 🎯 Smart Agent Behavior

The agent understands context:
- ✅ "What's the weather in Jerusalem?" → Uses Israel tool
- ✅ "I'm visiting New York, what's the forecast?" → Uses USA tool (40.71, -74.01)
- ✅ "Tell me about weather in Tel Aviv and Los Angeles" → Calls both tools
- ✅ "Is it raining in Chicago right now?" → Routes to USA tool

---

## 📂 Project Structure

```
MCP Weather/
├── host.py                  # Main chat host (OpenAI + tool orchestration)
├── client.py                # MCP client connector
├── weather_Israel.py        # Israel MCP server (Playwright + Web)
├── weather_USA.py           # USA MCP server (NWS API)
├── pyproject.toml           # Dependencies and project metadata
├── uv.lock                  # Locked dependency versions
├── .env.example             # Template for environment variables
├── .env                     # Your API keys (git-ignored)
├── README.md                # This file
└── .gitignore               # Git exclusion rules
```

---

## 🐛 Troubleshooting

### ❌ `OPENAI_API_KEY is missing`

**Problem**: The agent can't find your API key.

**Solution**:
1. Verify `.env` exists in the project root (same folder as `host.py`)
2. Check the file contains: `OPENAI_API_KEY=sk-your-actual-key-here`
3. Restart the host: `uv run .\host.py`

### ❌ Chromium browser won't launch

**Problem**: "Failed to launch browser" error.

**Solution**:
```powershell
uv run playwright install chromium
```

If still failing, check disk space (Chromium needs ~500 MB).

### ❌ Connection timeout or API errors

**Problem**: "net::ERR_CONNECTION_RESET" or request failures.

**Solution**:
- Check your internet connection
- Verify your OpenAI API key is valid at [platform.openai.com](https://platform.openai.com)
- Check API usage and billing

### ❌ Israel browser opens but search fails

**Problem**: City search doesn't return suggestions.

**Explanation**: The Weather2day autocomplete only works on the `/forecast` page. The tool automatically returns to that page before each search, but if it fails:

**Solution**:
- Verify Chromium is up to date: `uv run playwright install --with-deps chromium`
- Ensure you have internet connectivity to `weather2day.co.il`
- Check for browser pop-ups or cookie banners (the agent handles these, but very slow connections may timeout)

### ❌ "A server fails to connect"

**Problem**: MCP server connection error.

**Solution**:
```powershell
# Run from the project directory
Set-Location .\project-template
uv run .\host.py
```

---

## ❓ FAQ

**Q: How does the agent decide which tool to use?**  
A: OpenAI's GPT-4o-mini reads your question and selects the best tool based on the context (country/region mentioned, coordinates provided, etc.). It's not rule-based—it uses language understanding.

**Q: Can I ask about multiple regions in one query?**  
A: Yes! The agent can call multiple tools. Try: "What's the weather in Tel Aviv and New York?"

**Q: Why does the Israel browser open visibly?**  
A: Playwright automates Weather2day by typing into the live search, selecting results, and reading the page. Headless mode (invisible) doesn't work with this site's JavaScript-heavy autocomplete, so the browser runs visibly.

**Q: How much does this cost?**  
A: You're billed by OpenAI based on API calls. Each query costs ~$0.001–$0.01 depending on response length. Israel web scraping is free; USA API is free (NWS is public).

**Q: What if I want to add more regions?**  
A: Create a new MCP server (e.g., `weather_Europe.py`) and register it in `host.py` under `self.mcp_clients`. See the existing servers for the pattern.

**Q: Is my API key safe?**  
A: Yes. Your `.env` is excluded from Git and stored locally only. Never paste your key in code or public chat.

**Q: Can I use this in production?**  
A: This is a demo project. For production:
- Use async request queuing
- Add logging and error recovery
- Cache forecasts (weather changes hourly, not per-query)
- Set up monitoring and alerts
- Use environment-based configuration

---

## 🔒 Security

| ⚠️ **Do** | ❌ **Don't** |
|-----------|-----------|
| ✅ Keep `.env` local and private | ❌ Commit `.env` to Git |
| ✅ Rotate API keys regularly | ❌ Share your API key |
| ✅ Use environment variables in production | ❌ Hardcode secrets in code |
| ✅ Check API billing limits | ❌ Leave quota unlimited |
| ✅ Use HTTPS for API calls | ❌ Use HTTP in production |

**If your API key is exposed**:
1. Revoke it immediately in [OpenAI Dashboard](https://platform.openai.com/account/billing/overview)
2. Generate a new key
3. Update `.env`

---

## 📝 License

This project is provided as-is for educational purposes. See LICENSE for details.

---

## 🤝 Contributing

Have ideas to improve the agent? Contributions are welcome!

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 📞 Support

- 🐛 Report bugs via GitHub Issues
- 💡 Suggest features in Discussions
- 📧 For security issues, email privately (do not open a public issue)

---

**Happy forecasting! 🌦️☀️**