# MCP Weather Assistant

An interactive weather assistant built with the Model Context Protocol (MCP). The host connects to two local MCP servers, publishes their tools to an OpenRouter-compatible language model, and lets the model decide when to retrieve weather information.

## Features

- Weather forecasts for locations in the United States through the National Weather Service API.
- Active weather alerts for a United States state.
- Israeli weather forecasts through the `weather2day.co.il` website and a visible Chromium browser controlled by Playwright.
- One interactive terminal chat interface.
- Multiple MCP servers connected over stdio.
- Automatic tool discovery and namespacing to avoid collisions between servers.

## Project Structure

| File | Purpose |
| --- | --- |
| `host.py` | Main application. Connects to MCP servers, calls OpenRouter, routes tool calls, and runs the chat loop. |
| `client.py` | Reusable MCP stdio client wrapper. Starts a server with the current Python interpreter and lists its tools. |
| `weather_USA.py` | MCP server backed by the National Weather Service API. |
| `weather_Israel.py` | MCP server backed by `weather2day.co.il` and Playwright. |
| `pyproject.toml` | Python project metadata and declared dependencies. |
| `uv.lock` | Locked dependency versions for uv-based environments. |
| `.env` | Local environment variables. This file is ignored by Git. |

## Requirements

- Windows, macOS, or Linux.
- Python 3.13 or newer.
- An OpenRouter API key.
- Internet access to OpenRouter, `api.weather.gov`, and `weather2day.co.il`.
- Chromium, installed through Playwright, for Israeli weather queries.
- A virtual environment is recommended.

## Installation

### Using uv

From the project directory:

```powershell
uv sync
uv run playwright install chromium
```

The project currently imports `httpx` directly. If it is not already present in the locked environment, install it with:

```powershell
uv add httpx
```

### Using standard Python tooling

```powershell
py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install anthropic mcp python-dotenv playwright openai google-genai httpx
python -m playwright install chromium
```

On macOS or Linux, activate the environment with:

```bash
source .venv/bin/activate
```

The declared dependencies include several provider SDKs that are not currently used by `host.py`; they remain part of the project metadata for compatibility with the template.

## Configuration

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

```dotenv
OPENROUTER_API_KEY=your_openrouter_api_key
```

`host.py` loads this file with `python-dotenv` and sends the key as a Bearer token to OpenRouter. Do not commit `.env` or expose the key in source control, logs, screenshots, or error reports.

The current model is configured in `host.py`:

```python
MODEL = "nvidia/nemotron-3-super-120b-a12b:free"
```

Change this constant if you want to use another OpenRouter model that supports tool calling.

## Running the Assistant

With uv:

```powershell
uv run python host.py
```

With an activated virtual environment:

```powershell
python host.py
```

You should see a startup message followed by a `Query:` prompt. Type a question and press Enter. Type `quit` to stop the application.

Example questions:

```text
What is the forecast for 34.05, -118.25?
Are there any active weather alerts in California?
What is the weather forecast in Tel Aviv?
```

The host prints tool calls as they occur, followed by the model's final response.

## MCP Servers and Tools

### United States server

`weather_USA.py` starts an MCP server named `weather-USA` and provides:

- `get_alerts_in_USA(state)`
  - `state`: two-letter state code such as `CA` or `NY`.
  - Uses the NWS active-alerts endpoint.
- `get_forecast_in_USA(latitude, longitude)`
  - `latitude`: decimal latitude.
  - `longitude`: decimal longitude.
  - Resolves the location through the NWS points endpoint, then returns the first five forecast periods.

The NWS API request uses `Accept: application/geo+json` and a custom `User-Agent`.

### Israel server

`weather_Israel.py` starts an MCP server named `weather-Israel` and provides:

1. `open_weather_forecast_israel()`
   - Opens a non-headless Chromium browser and navigates to the Israeli forecast website.
2. `enter_weather_forecast_city_israel(city)`
   - Enters a city name and waits for autocomplete suggestions.
3. `select_weather_forecast_city_israel()`
   - Selects the first autocomplete suggestion and waits for the forecast page.
4. `get_forecast_content_israel()`
   - Extracts visible text from the loaded page, cleans empty lines, and limits the result to 4,000 characters.

The Israeli tools are stateful and must be called in order. The browser must be opened before entering a city, and a city must be selected before extracting the forecast.

## Architecture

```text
User terminal
    |
    v
host.py (ChatHost)
    |-- OpenRouter chat-completions API
    |
    |-- client.py -> weather_USA.py -> api.weather.gov
    |
    `-- client.py -> weather_Israel.py -> Playwright -> weather2day.co.il
```

At startup, `ChatHost` creates one `MCPClient` for each weather server. Each client launches its server as a child process using the same Python interpreter as the host. The host discovers all MCP tools and exposes them to OpenRouter using function-calling schemas.

To prevent duplicate names, tools are exposed to the model as:

```text
<server_script_name>__<tool_name>
```

For example, the USA alert tool is exposed as `weather_USA__get_alerts_in_USA`. When OpenRouter requests a tool, the host maps that public name back to the owning MCP client and original tool name, executes it, and sends the result back into the model conversation.

## Running an Individual MCP Server

Each server can be started directly for MCP-compatible clients or for basic smoke testing:

```powershell
python weather_USA.py
python weather_Israel.py
```

These programs use MCP stdio transport, so they are intended to communicate with an MCP client rather than display a normal web page or command prompt.

## Troubleshooting

### `ModuleNotFoundError: No module named 'httpx'`

Install the missing dependency:

```powershell
uv add httpx
```

or:

```powershell
python -m pip install httpx
```

### Chromium does not start

Install the Playwright browser binary:

```powershell
python -m playwright install chromium
```

The Israeli server intentionally launches Chromium with `headless=False`, so a desktop session is required for that provider.

### OpenRouter authentication fails

Check that `.env` is in the same directory as `host.py`, that the variable is named exactly `OPENROUTER_API_KEY`, and that the key is active. Restart the host after changing the file.

### No tools are available

Confirm that both server scripts exist in the project root and that the host is started from that directory. The host currently uses the relative paths `./weather_USA.py` and `./weather_Israel.py`.

### A weather request fails

The application depends on external services. Check internet access, the NWS response for the requested coordinates or state, and whether the Israeli website's HTML selectors have changed.

## Security and Operational Notes

- `host.py` and the NWS client disable TLS certificate verification with `verify=False`. This may be necessary in the current network environment, but it reduces transport security and should be replaced with normal certificate verification in production.
- OpenRouter receives the user's query and the results returned by weather tools.
- The Israeli provider opens a visible browser and scrapes the page's body text. Website layout changes can break the selectors or alter the extracted content.
- The application has no persistent conversation history; each terminal query starts a new model message list.
- Errors are printed to the terminal and are not written to a logging service.

## Development Notes

The MCP server scripts expose tools through `FastMCP` decorators and use async functions for network and browser operations. Keep the stdio channel reserved for MCP protocol traffic when modifying a server; diagnostic output should be handled carefully so it does not corrupt protocol communication.

There are currently no automated tests in the repository. A useful next test layer would mock the NWS responses, OpenRouter tool-call responses, and Playwright page interactions so the orchestration can be verified without network access or a browser.

## License

No license file is currently included in this repository.