# Weather MCP Server

Local [Model Context Protocol](https://modelcontextprotocol.io/) server in Python that
fetches real weather data from the [Open-Meteo](https://open-meteo.com/) API
(no API key required). Exposes one tool, `get_weather`, over stdio.

## Tool

`get_weather(city: str) -> dict`

Resolves the city via Open-Meteo Geocoding, fetches current conditions via
Open-Meteo Forecast, and returns structured output for agents plus a
human-readable `summary`.

Example return:

```json
{
  "city": "Amsterdam",
  "country": "The Netherlands",
  "latitude": 52.37,
  "longitude": 4.89,
  "temperature_c": 16.8,
  "apparent_c": 15.6,
  "humidity_pct": 59,
  "wind_kph": 6.1,
  "weather_code": 0,
  "description": "Clear sky",
  "summary": "Amsterdam (The Netherlands): Clear sky, 16.8°C (feels 15.6°C), wind 6.1 kph, humidity 59%"
}
```

## Requirements

- Python 3.10+
- Dependencies in `requirements.txt`: `mcp`, `httpx`, `pydantic`
  (dev: `pytest`, `pytest-asyncio`, `respx`)

## Setup

```bash
python -m venv venv
./venv/bin/pip install -r requirements.txt
```

## Run

Stdio transport (stdout is reserved for JSON-RPC — logs go to stderr):

```bash
./venv/bin/python server.py
```

Client config (`mcp.json` / `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "weather": {
      "command": "<absolute-path>/my-mcp-server/venv/bin/python",
      "args": ["<absolute-path>/my-mcp-server/server.py"]
    }
  }
}
```

## Tests

Mocked suite (no live HTTP) plus a live check:

```bash
./venv/bin/python -m pytest tests/ -v
./venv/bin/python -c "import asyncio, json, server; print(json.dumps(asyncio.run(server.get_weather('Amsterdam')), indent=2))"
```

## Structure

```
server.py              MCPServer("weather") + get_weather tool, stdio entrypoint
schemas.py             WeatherOutput / GeocodedLocation pydantic models
services/geocode.py    City -> (lat, lon) via Open-Meteo Geocoding
services/weather_api.py  (lat, lon) -> current conditions via Open-Meteo Forecast
tests/                 Mocked pytest suite (respx)
requirements.txt
weather_server.py      Original hardcoded stub (kept for reference)
```

## Notes

- No secrets or `.env` needed (Open-Meteo is keyless).
- Errors surface as `ValueError` with a friendly message
  (unknown city, timeout, HTTP error).