Metadata-Version: 2.4
Name: epwforge-mcp
Version: 0.1.5
Summary: MCP server for EPWForge — let Claude and other AI agents generate climate-stressed weather files (EPW, DDY) for any global location. Custom TMYx / AMY synthesis from ERA5, CMIP6 future-climate morphing (4 SSPs, 7 percentiles, 21-model ensemble), urban heat island presets, extreme-event injection (heat waves, cold snaps, humidity & wind compound events with per-event intensity), and wildfire smoke overlays. For EnergyPlus, OpenStudio, IES VE, eQUEST and any EPW-consuming workflow.
Project-URL: Homepage, https://epwforge.com
Project-URL: Repository, https://github.com/guzz-labs/epwforge-mcp
Project-URL: Issues, https://github.com/guzz-labs/epwforge-mcp/issues
Author-email: Guzzlabs <tuna@guzzlabs.com>
License: MIT
License-File: LICENSE
Keywords: ai-agent,amy,ashrae-design-day,building-energy-modeling,building-energy-simulation,claude,climate-adaptation,climate-deltas,climate-resilience,cmip6,cold-snap,compound-events,custom-weather-file,ddy,energy-modeling,energyplus,epw,epwforge,equest,era5,extreme-events,future-weather,guzzlabs,heat-wave,ies-ve,mcp,mcp-server,model-context-protocol,openstudio,ssp,tmy,tmyx,uhi,urban-heat-island,weather-file,weather-morphing,wildfire-smoke
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: httpx[http2]>=0.27.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# epwforge-mcp

<!-- mcp-name: io.github.guzz-labs/epwforge-mcp -->

> MCP server for [EPWForge](https://epwforge.com) — give Claude, Cursor, and other AI agents the ability to generate, morph, and download weather files for building energy simulation.

**Status:** Live on PyPI and the [official MCP Registry](https://registry.modelcontextprotocol.io). One tool call → one EPW. Production backend, Pro-tier features wired in.

## What is EPWForge?

EPWForge generates and morphs weather files (`.epw`, `.ddy`) for building energy simulation tools — EnergyPlus, OpenStudio, IES VE, eQUEST, and any workflow that consumes EPW. The platform supports:

- **TMYx generation anywhere** — typical meteorological years synthesized from ERA5 reanalysis for any global lat/lon
- **AMY (Actual Meteorological Year)** — historical hourly weather for hindcasting and calibration
- **CMIP6 climate morphing** — apply future-scenario deltas (SSP1-2.6, SSP2-4.5, SSP3-7.0, SSP5-8.5) at 7 warming percentiles
- **Urban Heat Island adjustment** — Stewart & Oke LCZ presets (suburban / urban / dense_urban)
- **Extreme event injection** — heat waves, cold snaps, humidity events, wind events, with auto-compound blending and per-event intensity (1-10 slider, AR6-auto-fill under SSP)
- **Wildfire smoke overlays** — CAMS-derived AOD with Beer-Lambert solar attenuation, RH bump, temp shift
- **Per-model CMIP6 ensembles** — up to 21 morphed EPWs (one per model) for inter-model uncertainty analysis

## Tools

Four MCP tools, each mapping 1:1 to an EPWForge API endpoint:

| Tool | Purpose |
|---|---|
| `generate_weather_file` | The workhorse. One call returns an EPW with any combination of TMY/AMY/SSP basis, UHI, extreme events, and smoke. |
| `generate_design_day` | DDY file for EnergyPlus design-day sizing, computed from the same enriched hourly data. |
| `generate_ensemble` | Per-model CMIP6 ensemble — one morphed EPW per climate model (Pro plan). |
| `find_station` | Search weather stations near a coordinate (returns name, WMO ID, distance). |

Most users will only ever need `generate_weather_file`. Compose options into one call instead of chaining tools.

## Quick example

```python
# What an AI agent might call to get a worst-case design weather file:
generate_weather_file(
    lat=40.71,
    lon=-74.01,
    ssp="ssp585",      # SSP5-8.5 emissions
    year=2090,         # End-of-century
    percentile=90,     # 90th percentile warming
    uhi="urban",       # Stewart-Oke urban LCZ
    events="heatwave,hothumid",  # Auto-compound heat + humidity
    event_duration=14,
    smoke=True,
    smoke_intensity=5,
    save_to="/tmp/nyc_2090_worst_case.epw",
)
```

Returns `{filename, saved_to, bytes_written, scenario, lat, lon, ...}` — no inline base64 bloat when `save_to` is set.

## Install

```bash
pip install epwforge-mcp
```

Requires Python ≥ 3.10.

## Connecting to Claude / Cursor

Add to your MCP client config (Claude Desktop's `claude_desktop_config.json`, Cursor's MCP settings, etc.):

```json
{
  "mcpServers": {
    "epwforge": {
      "command": "epwforge-mcp",
      "env": {
        "EPWFORGE_API_KEY": "sk_live_..."
      }
    }
  }
}
```

Generate an API key at [epwforge.com/account](https://epwforge.com/account).

## Plan requirements

| Feature | Plan |
|---|---|
| TMYx / AMY basis (`generate_weather_file`, `generate_design_day` without SSP) | Starter |
| UHI / events / smoke adjustments | Starter |
| SSP future-climate morphing | Pro |
| `generate_ensemble` (per-model CMIP6) | Pro |
| `find_station` | Free |

Tier enforcement happens at the API; the MCP surfaces 403s as `"Plan upgrade required — upgrade at https://epwforge.com/pricing"`.

## Environment variables

| Variable | Purpose | Default |
|---|---|---|
| `EPWFORGE_API_KEY` | Bearer token for the EPWForge API | required |
| `EPWFORGE_BASE_URL` | Override the API host (mainly for testing) | `https://epwforge.com` |

## Behavior notes

- **File output:** every file-generating tool accepts `save_to` (or `save_to_dir` for ensembles). When provided, the EPW is written to disk and the tool returns the path. When omitted, the EPW is returned base64-encoded in the response (≈ 250 KB for a typical year). **`save_to` is recommended** to keep agent context lean.
- **Compound events:** `events="heatwave,hothumid"` automatically blends `hothumid`'s humidity onto the heatwave at 50%. `events="coldsnap,coldwindy"` does the same for wind onto a cold snap. The secondary is folded into the primary stitch — not stitched separately.
- **Event placement:** events are anchored at the cell's hottest day (heat-family) or coldest day (cold-family) and centered for the requested duration. The peak day's diurnal cycle is sustained across the event, producing 30 days of peak heat for a 30-day request — not a stretched 14-day shape.
- **Smoke + heat compound:** when both are active, smoke aligns to the same anchor day and pads with peak AOD on the heat event's shoulders so solar is fully attenuated across the entire event window.
- **AR6 SSP auto-fill:** with an SSP scenario active, unspecified event intensities are auto-filled from IPCC AR6 ensemble factors for the cell's region. Cold events stay at intensity 5 (no future amplification) because recent observations (Texas 2021, polar-vortex disruption) don't yet support the AR6 ensemble's cold-side dampening. Pass `intensity_auto=false` to disable.

## Development

```bash
git clone https://github.com/guzz-labs/epwforge-mcp
cd epwforge-mcp/python
uv sync
uv run epwforge-mcp  # runs the stdio server
```

To test against a local API:

```bash
EPWFORGE_BASE_URL=http://localhost:3000 \
EPWFORGE_API_KEY=sk_live_... \
uv run epwforge-mcp
```

## Links

- **Website:** [epwforge.com](https://epwforge.com)
- **API docs / OpenAPI spec:** [epwforge.com/docs](https://epwforge.com/docs)
- **Maker:** [Guzzlabs](https://guzzlabs.com)
- **Issues:** [github.com/guzz-labs/epwforge-mcp/issues](https://github.com/guzz-labs/epwforge-mcp/issues)

## License

MIT
