Metadata-Version: 2.4
Name: weather-shap-mcp
Version: 0.1.0
Summary: MCP server for 7-day weather intelligence — rain, UV, heat & air quality with real SHAP explainability
Project-URL: Homepage, https://github.com/SuMayaBee/weather-mcp
Project-URL: Repository, https://github.com/SuMayaBee/weather-mcp
Author-email: SuMayaBee <sumaiya.0fficial369@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai,explainability,forecast,mcp,shap,weather,xgboost
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pandas>=2.1.0
Requires-Dist: scikit-learn>=1.4.0
Requires-Dist: shap>=0.45.0
Requires-Dist: xgboost>=2.0.0
Description-Content-Type: text/markdown

# Weather MCP

MCP server that predicts rain for the next 7 days in any city and explains the
prediction using SHAP values. Mirrors Part 3 of `weather_shap.ipynb`:
**XGBoost + SHAP TreeExplainer + live Open-Meteo data**.

## Tools

| Tool | Purpose |
| --- | --- |
| `predict_rain_7day` | 7-day rain probability forecast for a city. Trains an XGBoost model on 2 years of historical data on first call, then caches it. |
| `explain_rain_prediction` | SHAP factors for a specific forecasted day — which feature pushed the probability up or down and by how much. |
| `city_model_info` | Metadata about the cached model (accuracy, training window). |

Data source: [Open-Meteo](https://open-meteo.com/) (no API key required).

## Install

```bash
cd weather-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

This installs the `weather-mcp` console script, which is what the MCP clients
below will launch.

## Running locally (smoke test)

```bash
weather-mcp
```

The server speaks MCP over stdio — it will sit waiting for JSON-RPC. Use Ctrl-C
to stop. Real testing happens through one of the clients below.

## Connect to Claude Desktop

Edit `~/.config/Claude/claude_desktop_config.json` (Linux) or
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "weather": {
      "command": "/absolute/path/to/weather-mcp/.venv/bin/weather-mcp"
    }
  }
}
```

Restart Claude Desktop. You should see a 🔌 icon listing `predict_rain_7day`,
`explain_rain_prediction`, and `city_model_info`.

## Connect to Cursor

Settings → MCP → Add new MCP server:

- **Name:** `weather`
- **Command:** `/absolute/path/to/weather-mcp/.venv/bin/weather-mcp`

## Connect to VS Code (Continue extension or any MCP-aware client)

Add to your client's MCP config:

```json
{
  "mcpServers": {
    "weather": {
      "command": "/absolute/path/to/weather-mcp/.venv/bin/weather-mcp",
      "args": []
    }
  }
}
```

## Example conversation

> **You:** Will it rain in Tokyo over the next 7 days?
>
> *(client calls `predict_rain_7day(city="Tokyo")`)*
>
> **Claude:** Tomorrow shows a 78% chance of rain, day 3 drops to 12%, …
>
> **You:** Why is day 1 so high?
>
> *(client calls `explain_rain_prediction(city="Tokyo", day_index=0)`)*
>
> **Claude:** The biggest driver is forecasted precipitation = 8.4 mm
> (+1.92 log-odds), reinforced by a higher-than-usual min temperature …

## How it works

1. **Geocode** the city via Open-Meteo's geocoding endpoint.
2. **Train** an XGBoost binary classifier on ~2 years of daily archive data
   (`precipitation, temp_max, temp_min, windspeed` → did it rain that day,
   derived from WMO weather codes). The trained model is cached per location.
3. **Predict** by fetching the live forecast and running `predict_proba`.
4. **Explain** with `shap.TreeExplainer` — exact Shapley values for the trained
   model, surfaced as ranked factors per day.

## Notes

- Models are cached in-process; restarting the server retrains on next call.
- A given location key rounds lat/lon to two decimals, so "Tokyo" and a query
  near Tokyo Tower share the same model.
- `explain_rain_prediction` will auto-run a 7-day prediction if you ask it
  before `predict_rain_7day` for that city.
