# MCP Weather Agent

An MCP (Model Context Protocol) server that turns a public REST API into
tools an AI agent can call directly — geocode a place name, then pull
current conditions or a multi-day forecast, with typed inputs and typed,
structured outputs instead of free text.

This is a small, self-contained example of the same pattern used to build
production agent-tool servers for enterprise systems: typed tool schemas,
input validation, retry/timeout handling on outbound calls, and structured
logging, so an agent's tool calls are predictable and debuggable.

## Why this exists

Most "AI agent" demos either hardcode a single API call or let the model
free-form parse HTML. Neither scales past a toy example. This project shows
the pattern that does: each capability is a small, independently testable
tool with a strict input/output contract, and the server itself knows
nothing about *how* an agent decides to call it — that separation is what
lets the same server work behind Claude Desktop, Claude Code, or a custom
LangGraph agent without changes.

## Architecture

```
Agent (Claude Desktop / Claude Code / LangGraph, etc.)
        │  MCP protocol (stdio transport)
        ▼
FastMCP server (server.py)
   ├─ geocode_location(location_name)      → GeocodeResponse
   ├─ get_current_weather(lat, lon)        → CurrentWeather
   └─ get_forecast(lat, lon, days)         → ForecastResponse
        │  validated params → httpx call w/ retry+timeout
        ▼
Open-Meteo REST API (geocoding + forecast, no API key required)
```

Each tool's return value is a Pydantic model, not a string — so a calling
agent (or a downstream function in a larger pipeline) can read
`result.temperature_c` directly instead of re-parsing prose.

## Design decisions & trade-offs

- **Open-Meteo over a keyed provider**: no API key means anyone cloning this
  repo can run it in under a minute. A production system would swap in
  whatever provider the business already pays for.
- **Structured Pydantic outputs over raw JSON passthrough**: costs a bit of
  mapping code per tool, but means malformed upstream responses fail loudly
  at the boundary instead of silently confusing the agent three steps later.
- **Bounded retries in `_get_json`, not a retry library**: for a 3-tool demo
  a dependency like `tenacity` is unnecessary weight; the same slot is where
  you'd add exponential backoff or circuit-breaking for a heavier-traffic
  service.
- **stdio transport by default**: simplest to run locally via Claude
  Desktop/Claude Code. Swapping to Streamable HTTP (see `mcp.server.fastmcp`
  docs) is a one-line change to `mcp.run(transport=...)` when you need a
  server other machines can call.

## Running it

```bash
python -m venv .venv
source .venv/bin/activate          # .venv\Scripts\activate on Windows
pip install -e ".[dev]"

pytest                              # run the offline unit test suite
python -m mcp_weather_agent.server  # run the server over stdio
```

### Connecting it to Claude Desktop or Claude Code

Add to your MCP config (see `examples/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "weather-agent": {
      "command": "python",
      "args": ["-m", "mcp_weather_agent.server"],
      "cwd": "/absolute/path/to/mcp-weather-agent"
    }
  }
}
```

Restart the client, and the three tools (`geocode_location`,
`get_current_weather`, `get_forecast`) become available for the agent to call.

## Tools

| Tool | Input | Output |
|---|---|---|
| `geocode_location` | `location_name: str`, `max_results: int` | Ranked list of name/country/lat/lon candidates |
| `get_current_weather` | `latitude: float`, `longitude: float` | Current temperature, apparent temp, wind, precipitation |
| `get_forecast` | `latitude: float`, `longitude: float`, `days: int` | Daily high/low/precipitation for up to 16 days |

## Testing

`tests/test_server.py` monkeypatches the HTTP layer so the suite runs fully
offline and fast — useful for CI, and for making sure tool-shape regressions
(a renamed field, a missing key) get caught before an agent ever sees them.

## Possible extensions

- Swap stdio for Streamable HTTP transport and deploy behind auth for
  multi-client access.
- Add a `severe_weather_alerts` tool against a provider that supports it.
- Add response caching (short TTL) to cut duplicate calls when an agent
  re-checks the same location across a multi-step plan.

## License

MIT — see `LICENSE`.