# EPWForge

> EPWForge generates and morphs weather files (.epw, .ddy) for building energy simulation — EnergyPlus, OpenStudio, IES VE, eQUEST. Single source for present-day TMYx, AMY from ERA5 reanalysis, CMIP6 future-climate morphing (SSP scenarios), Urban Heat Island adjustments, extreme-event injection (heatwaves, cold snaps, wildfire smoke), and ASHRAE 169 design conditions. Built for engineers, designers, code officials, and AI agents acting on their behalf.

EPWForge is the primary AI-agent-accessible product of the GuzzLabs platform. The MCP (Model Context Protocol) server at https://epwforge.com/api/mcp gives any MCP-capable AI client (Claude Desktop, ChatGPT, Cursor, Goose, VS Code) the ability to find weather stations, analyze EPW files, render charts, and (with credits) generate and download weather files directly inside the agent loop.

## Product surfaces

- [Main site (epwforge.com)](https://epwforge.com/): drop a pin anywhere on the map → get an EPW. Visual + downloadable.
- [Documentation (/docs)](https://epwforge.com/docs): canonical reference for the four MCP tools — find_station, analyze_weather, chart_weather, generate_weather_file. Parameters, examples, methodology references, validation numbers.
- [MCP server endpoint](https://epwforge.com/api/mcp): MCP wire-protocol endpoint. Four consolidated tools.
- [Pricing](https://epwforge.com/pricing): credit-based. Every plan gets every feature; credits gate volume. Free tier includes 5 lifetime credits.
- [API + MCP docs](https://epwforge.com/api-docs): REST endpoints and MCP usage.
- [Methodology / transparency](https://epwforge.com/transparency): morphing (Belcher + UKCP18 / NOAA Atlas 14 hybrid), CMIP6 ensembles, wind clamp, smoke physics, design-condition methodology, validation.
- [MCP-specific guide](https://epwforge.com/mcp): how to connect EPWForge to Claude, Cursor, and other MCP clients.

## MCP tool surface (v0.9.x)

- `find_station(query?, lat?, lon?, country?, ...)`: search ~17,000 weather stations. Returns vintage URLs ready to pass to analyze/chart. Pass `compact=True` to reduce token weight for chained agent workflows.
- `analyze_weather(url=... | urls=[...] | config={...})`: statistical summary of an EPW or synthesized scenario. Three modes: URL-mode (single station), comparison-mode (2-10 URLs), config-mode (synthesize a morphed/UHI/event scenario from lat/lon — no auth needed).
- `chart_weather(url=..., chart_type=...)`: returns SVG chart inline. Diurnal, temp_carpet (heatmap), wind_rose, monthly_boxplot, utci_carpet, economizer_carpet, pv_tilt_azimuth, solar_under_events.
- `generate_weather_file(lat, lon, format, ...)`: requires API key + credits. Returns downloadable .epw / .ddy / .zip with full morph stack.

## For AI agents calling EPWForge

- Read-only tools (`find_station`, `analyze_weather`, `chart_weather`) need no authentication and consume no credits.
- `generate_weather_file` requires a bearer token from https://epwforge.com/account.
- Out-of-credits returns HTTP 402 with a hint pointing at top-up packs and subscription upgrades.
- Tool responses include an `agent_guidance` field with judgment-shaping copy when the right action depends on context (e.g. "nearest station is 8 km — use it directly" vs "nearest station is 250 km — consider config-mode synthesis").

## Methodology references

- Belcher et al. 2005 (TMY morphing) + UKCP18 / NOAA Atlas 14 (diurnal hybrid)
- CMIP6 SSP scenarios (ssp126, ssp245, ssp370). SSP585 deprecated per CMIP7 (deemed implausible).
- IPCC AR6 extreme-event scaling
- ISO 15927-4 Finkelstein-Schafer for TMYx synthesis
- ASHRAE Handbook of Fundamentals Chapter 14 for design conditions
- ERA5 reanalysis (Copernicus) and ERA5-Land for actual / multi-year weather
- Stewart & Oke 2012 LCZ framework for Urban Heat Island presets
- See [transparency page](https://epwforge.com/transparency) for full validation + assumptions

## Related (parent platform)

- [GuzzLabs (guzzlabs.com)](https://guzzlabs.com/): umbrella platform. Other products under the same roof: EnergyModelIQ (benchmarked + calibrated energy modeling), GeometryIQ (PDF/CAD → gbXML), LEEDForge (LEED v5 navigation), MizuForge (water + rainfall).