# ERA5 SMI

Calculate monthly soil moisture index (SMI) for any region based on
ERA5-Land. Data comes in via an MCP server, the index is computed with a
KDE transformation. Figures are generated using SKILLS.md files.

## What you need

- [uv](https://astral.sh/uv/)
- A CDS account and API key in `~/.cdsapirc` (see
  https://cds.climate.copernicus.eu/api-how-to)

## Setup

```bash
cd mcp/era5-mcp && uv sync && cd ../..
uv sync
```

To use the MCP server, point your client at `mcp.json` in the root.

## Run the MCP server in VS Code

1. **Install the environments** (first time only):

   ```bash
   cd mcp/era5-mcp && uv sync && cd ../..
   uv sync
   ```

2. **Make the launcher executable** (first time only):

   ```bash
   chmod +x mcp/era5-mcp/start_era5_mcp.sh
   ```

3. **Register the server**: create `.vscode/mcp.json` in the project root
   with the path to the launcher. A relative path works if you open VS Code
   from the project folder; use an absolute path otherwise:

   ```json
   {
     "servers": {
       "era5": {
         "type": "stdio",
         "command": "/absolute/path/to/era5-smi-project/mcp/era5-mcp/start_era5_mcp.sh",
         "args": []
       }
     }
   }
   ```

4. **Reload the window**: `Ctrl+Shift+P` → "Developer: Reload Window".
   The server is listed under "MCP: Manage Servers" and should show as
   running (green).

5. **Use it**: ask the agent to call the tools
   `fetch_era5_land_soil_moisture` and `extract_point_timeseries`. The
   server only starts when the agent invokes it. Logs (with `[DEBUG]`
   lines) appear in the Output panel → MCP.

To verify the server works on its own, run `bash mcp/era5-mcp/start_era5_mcp.sh`
in a terminal — it starts and waits on stdio (that's normal), `Ctrl+C` to stop.

## Usage

1. Download data with the MCP tool `fetch_era5_land_soil_moisture`.
2. Extract your point with `extract_point_timeseries`.
3. Use the **`calculate-smi` skill** to compute the index (see
   `skills/calculate-smi/SKILL.md`).
4. Use the **`plot-smi` skill** to make the figures (see
   `skills/plot-smi/SKILL.md`).

The skills are the interface; never run the scripts under
`skills/*/scripts/` directly.

## Layout

- `AGENTS.md` — instructions for running the pipeline
- `pyproject.toml` — environment for the skills (numpy, pandas, scipy, ...)
- `mcp.json` — config to connect an MCP client to the era5 server
- `mcp/era5-mcp/` — MCP server, the only thing that talks to the CDS API
  - `era5_server.py` — the server and its MCP tools
  - `start_era5_mcp.sh` — launcher for the server
  - `pyproject.toml` — server environment (cdsapi, fastmcp, xarray)
- `skills/`
  - `calculate-smi/` — turns a soil moisture CSV into an SMI series
    - `SKILL.md` — docs for the skill
    - `scripts/calculate_smi.py` — the script
  - `plot-smi/` — turns an SMI CSV into figures
    - `SKILL.md` — docs for the skill
    - `scripts/plot_smi.py` — the script
- `data/`
  - `raw/` — downloaded NetCDF files
  - `processed/` — extracted CSVs and SMI CSVs
  - `figures/` — output PNGs