# MCP Weather Forecast Server

A Model Context Protocol (MCP) server that enables LLMs to retrieve weather forecasts from Israeli websites using browser automation with Playwright. This project demonstrates how to build MCP tools that maintain state across sequential tool calls, allowing an LLM to control a browser interactively.

## Project Overview

This project implements an MCP server using the official Anthropic MCP SDK in Python. It provides tools for:
- Opening a browser and navigating to an Israeli weather forecast website
- Entering city names into search fields
- Selecting cities from autocomplete dropdowns
- Extracting weather data from the loaded page

The key feature is the global state mechanism that persists browser and page instances across different tool calls, enabling sequential operations on the same browser page.

## Architecture

### Components

- **host.py**: Main chat host that manages MCP clients and orchestrates tool calls with Anthropic's Claude API
- **weather_Israel.py**: MCP server implementing browser automation tools for Israeli weather forecasts
- **weather_USA.py**: MCP server implementing API-based weather tools for USA weather data
- **client.py**: MCP client implementation for connecting to MCP servers via stdio transport

### Global State Management

The `weather_Israel.py` module uses a `BrowserState` class to maintain global browser and page instances:
- `playwright`: The Playwright async context
- `browser`: The Chromium browser instance (headless=False for visibility)
- `page`: The browser page for navigation and interaction

This state persists across tool calls, allowing sequential operations like:
1. Open browser → 2. Enter city → 3. Select city → 4. Extract data

## Prerequisites

- Python 3.13 or higher
- `uv` package manager
- Anthropic API key (set in `.env` file)

## Installation

1. Clone the repository and navigate to the project directory:
```bash
cd project-template
```

2. Install dependencies using `uv`:
```bash
uv sync
```

3. Install Playwright Chromium browser:
```bash
uv run playwright install chromium
```

4. Set up your environment variables:
```bash
# Edit .env and add your ANTHROPIC_API_KEY
```

## Usage

### Running the MCP Server

Start the interactive chat host:
```bash
uv run host.py
```

This will:
- Connect to the configured MCP servers (weather_Israel.py and weather_USA.py)
- Start an interactive chat loop
- Allow you to ask questions that trigger tool calls

### Example Questions

Once the host is running, you can ask questions like:

**Israeli Weather:**
- "What is the weather in Jerusalem today?"
- "Tell me the forecast for Tel Aviv"
- "What's the current temperature in Haifa?"

**USA Weather:**
- "Are there any weather alerts for California?"
- "What's the forecast for New York City?"
- "Get the weather forecast for latitude 37.7749, longitude -122.4194"

### How It Works

When you ask a question, the system:
1. Sends your query to Claude via the Anthropic API
2. Claude determines which tools to call based on your question
3. The host executes the tools in sequence (e.g., open browser → enter city → select → extract)
4. Results are returned to Claude for final response generation
5. The answer is displayed in the chat

## MCP Tools

### weather_Israel.py Tools

#### `open_weather_forecast_israel()`
Launches a Chromium browser (headless=False) and navigates to https://www.weather2day.co.il/forecast.

#### `enter_weather_forecast_city_israel(city: str)`
Locates the search input field and types the given city name into it.
- **Parameter**: `city` - The name of the Israeli city (e.g., "Jerusalem", "Tel Aviv")

#### `select_weather_forecast_city_israel()`
Waits for the autocomplete dropdown to appear and clicks the first city in the list.

#### `extract_weather_forecast_israel()`
Extracts weather data from the loaded page, cleans up HTML and whitespace, and returns the text for LLM processing.

### weather_USA.py Tools

#### `get_alerts_in_USA(state: str)`
Gets weather alerts for a USA state.
- **Parameter**: `state` - Two-letter USA state code (e.g., CA, NY)

#### `get_forecast_in_USA(latitude: float, longitude: float)`
Gets weather forecast for a location in USA.
- **Parameters**: 
  - `latitude` - Latitude of the location
  - `longitude` - Longitude of the location

## Development

### Adding New MCP Servers

To add a new MCP server:

1. Create a new Python file (e.g., `weather_Europe.py`)
2. Import FastMCP and create an instance:
```python
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather-Europe")
```

3. Define tools using the `@mcp.tool()` decorator:
```python
@mcp.tool()
async def your_tool_name(param: str) -> str:
    """Tool description"""
    # Your implementation
    return result
```

4. Add the main entry point:
```python
def main():
    mcp.run(transport="stdio")

if __name__ == "__main__":
    main()
```

5. Register the server in `host.py` by adding it to the `mcp_clients` list:
```python
self.mcp_clients: list[MCPClient] = [
    MCPClient("./weather_USA.py"),
    MCPClient("./weather_Israel.py"),
    MCPClient("./weather_Europe.py")  # Add your new server
]
```

### Debugging

- The browser runs in headless mode by default. Set `headless=False` in `BrowserState.ensure_browser()` to see the browser actions.
- Check the console output for tool execution logs and error messages.
- Use the `@mcp.tool()` decorator's docstring to provide clear descriptions for the LLM.

## Troubleshooting

**Browser not launching**: Ensure Playwright Chromium is installed with `uv run playwright install chromium`

**Timeout errors**: The website might be slow or loading differently. Adjust timeout values in the tool functions.

**Selector not found**: The website structure may have changed. Update the CSS selectors in the tool functions.

**API errors**: Verify your Anthropic API key is correctly set in the `.env` file.

## License

This project is part of an academic project for learning MCP (Model Context Protocol) implementation.

## Acknowledgments

- Built with [Anthropic MCP SDK](https://github.com/anthropics/mcp-sdk-python)
- Powered by [Anthropic Claude](https://www.anthropic.com/)
- Browser automation powered by [Playwright](https://playwright.dev/)
- Dependency management with [uv](https://github.com/astral-sh/uv)