# 🌤️ Weather Israel — Agentic MCP Server with Browser Automation

> An AI-powered weather assistant that autonomously controls a browser to fetch real-time Israeli weather forecasts using the **Model Context Protocol (MCP)** and **Playwright**.

[![Python](https://img.shields.io/badge/Python-3.13+-blue?logo=python&logoColor=white)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-Protocol-purple)](https://modelcontextprotocol.io/)
[![Playwright](https://img.shields.io/badge/Playwright-Automation-green?logo=playwright)](https://playwright.dev/)
[![Gemini](https://img.shields.io/badge/Gemini_2.5-Flash-orange?logo=google)](https://ai.google.dev/)

---

## 📌 Overview

This project implements a custom **MCP (Model Context Protocol) Server** that gives an LLM autonomous browser control capabilities. Instead of relying on a traditional weather API, the system opens a real browser, navigates to an Israeli weather website, searches for a city, and extracts the live forecast — just like a human would.

The LLM (Gemini 2.5 Flash) acts as the **orchestrating agent**, deciding which tools to invoke and in what sequence, creating a fully autonomous agentic pipeline.

### Why is this interesting?

- **No API needed** — scrapes data directly from the web using browser automation
- **Agentic architecture** — the LLM decides which tools to call and when
- **MCP standard** — uses Anthropic's open protocol for tool communication
- **RAG pattern** — extracts page content and feeds it back to the LLM for reasoning

---

## 🎯 Project Goals

- Implement a custom **MCP Server** from scratch
- Use **Playwright** to add browser automation capabilities to an LLM
- Demonstrate **agentic tool-calling** with multi-step orchestration
- Build a complete **RAG pipeline** — retrieve data → augment context → generate response

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                         User Query                               │
│              "What's the weather in Tel Aviv?"                    │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                    host.py (Orchestrator)                         │
│              Gemini 2.5 Flash + Tool Calling                     │
└─────────────────────────┬───────────────────────────────────────┘
                          │ MCP Protocol
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│               weather_Israel.py (MCP Server)                     │
│                                                                  │
│   Tool 1: open_weather_forecast_israel()                         │
│   Tool 2: enter_weather_forecast_city_israel(city)               │
│   Tool 3: select_weather_forecast_city_israel()                  │
│   Tool 4: get_weather_page_content()                             │
└─────────────────────────┬───────────────────────────────────────┘
                          │ Playwright
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│              weather2day.co.il (Live Website)                     │
│         Real-time weather data scraped from browser               │
└─────────────────────────────────────────────────────────────────┘
```

---

## 🛠️ Tech Stack

| Technology | Purpose |
|---|---|
| **Python 3.13+** | Core language |
| **MCP SDK** | Model Context Protocol — exposes tools to the LLM |
| **Playwright** | Headless browser automation (Chromium) |
| **Gemini 2.5 Flash** | LLM for reasoning and tool orchestration |
| **httpx** | HTTP client for Gemini REST API calls |
| **uv** | Modern Python package manager |

---

## 📁 Project Structure

```
MCP/
├── weather_Israel.py     # MCP Server — Israeli weather tools (Playwright)
├── weather_USA.py        # MCP Server — US weather tools (API-based)
├── host.py               # Orchestrator — Gemini + MCP client integration
├── client.py             # Generic MCP client connector
├── pyproject.toml        # Dependencies and project metadata
├── .env.example          # Environment variable template
├── .gitignore            # Git ignore rules
├── uv.lock               # Locked dependencies
└── README.md             # This file
```

---

## 🔧 MCP Tools — `weather_Israel.py`

| # | Tool | Description |
|---|---|---|
| 1 | `open_weather_forecast_israel()` | Launches Chromium and navigates to the weather website |
| 2 | `enter_weather_forecast_city_israel(city)` | Types the city name into the search field using keyboard simulation |
| 3 | `select_weather_forecast_city_israel()` | Clicks the first autocomplete result from the dropdown |
| 4 | `get_weather_page_content()` | Extracts and cleans the visible text from the forecast page |

---

## ⚡ Prerequisites

- **Python 3.13** or higher
- **uv** package manager (`pip install uv`)
- **Gemini API Key** from [Google AI Studio](https://aistudio.google.com/app/apikey)

---

## 📦 Installation

### 1. Clone the repository

```bash
git clone https://github.com/yael3222664-alt/MCP.git
cd MCP
```

### 2. Install dependencies

```bash
uv sync
```

### 3. Install Chromium for Playwright

```bash
uv run playwright install chromium
```

### 4. Configure environment variables

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

```bash
GEMINI_API_KEY=your_gemini_api_key_here
```

> Get your free API key at [Google AI Studio](https://aistudio.google.com/app/apikey)

---

## 🚀 Running the Application

```bash
python -m uv run host.py
```

You'll see:

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

Query: 
```

---

## 💬 Example Queries & Output

### Query:
```
מה מזג האוויר בבני ברק?
```

### Agent Actions:
```
[Calling tool weather_Israel__open_weather_forecast_israel with args {}]
[Calling tool weather_Israel__enter_weather_forecast_city_israel with args {'city': 'בני ברק'}]
[Calling tool weather_Israel__select_weather_forecast_city_israel with args {}]
[Calling tool weather_Israel__get_weather_page_content with args {}]
```

### Response:
```
The current temperature in Bnei Brak is 30°C with wind speed of 15 km/h 
and gusts up to 37 km/h from the west. Humidity is at 52%.

Hourly forecast for today:
• 14:00 — 30°C, humidity 52%, wind 15 km/h
• 15:00 — 30°C, humidity 52%, wind 15 km/h
• 16:00 — 29°C, humidity 54%, wind 14 km/h
...
```

### More examples:
```
What's the weather in Jerusalem?
מה התחזית לחיפה?
How's the weather in Tel Aviv today?
What are the weather alerts in California?  (uses USA tools)
```

---

## � How It Works — Step by Step

1. **User asks a question** → `"What's the weather in Tel Aviv?"`
2. **Gemini analyzes** the query and identifies the required tools
3. **Tool 1** → Playwright opens a headless Chromium browser and navigates to the weather site
4. **Tool 2** → Playwright types the city name into the search field (character by character to trigger autocomplete)
5. **Tool 3** → Playwright clicks the first matching result in the dropdown
6. **Tool 4** → Playwright extracts all visible text from the forecast page
7. **Gemini receives** the raw page content and formulates a clean, structured answer
8. **User gets** a natural language response with temperature, wind, humidity, and hourly forecast

---

## 🧠 Key Design Decisions

- **Keyboard simulation** (`keyboard.type()`) instead of `fill()` — triggers the website's JavaScript autocomplete
- **Direct REST API calls** to Gemini with `httpx(verify=False)` — bypasses SSL issues in restricted network environments
- **Global browser state** — shared between tool calls so the same page instance persists across the multi-step workflow
- **Graceful error handling** — each tool validates state and returns clear error messages

---

## 🐛 Troubleshooting

| Issue | Solution |
|---|---|
| `uv: command not found` | Use `python -m uv` instead of `uv` |
| `GEMINI_API_KEY not found` | Create `.env` file with your API key |
| `429 Too Many Requests` | Rate limit — wait 1 minute or use a different API key |
| Browser doesn't open | Run `uv run playwright install chromium` |
| SSL errors | The code already disables SSL verification for restricted networks |

---

## 📚 Resources

- [MCP Documentation](https://modelcontextprotocol.io/)
- [Playwright Python Docs](https://playwright.dev/python/)
- [Gemini API Reference](https://ai.google.dev/docs)
- [uv Package Manager](https://docs.astral.sh/uv/)

---

## 📄 License

This project is open source and available for educational purposes.

---

**Built with Playwright 🎭 and the Model Context Protocol 🤖**