@cyanheads/epa-mcp-server 0.3.0 → 0.3.2

package/README.md

@@ -1,13 +1,13 @@
 <div align="center">
   <h1>@cyanheads/epa-mcp-server</h1>
-  <p><b>Access EPA environmental data — facility compliance (ECHO), toxic releases (TRI), Superfund sites, drinking water systems, environmental justice screening (EJScreen), and real-time air quality (AirNow) via MCP. STDIO or Streamable HTTP.</b>
-  <div>9 Tools • 2 Resources</div>
+  <p><b>Search and retrieve EPA environmental data: facility compliance (ECHO), toxic releases (TRI), Superfund sites, drinking water systems, environmental-justice screening (EJScreen), and real-time air quality (AirNow). STDIO or Streamable HTTP.</b>
   </p>
+  <div>9 Tools • 2 Resources</div>
 </div>
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.3.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/epa-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/epa-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/epa-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.3.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/epa-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/epa-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/epa-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -21,151 +21,143 @@
 
 ---
 
-## Tools
+## Overview
 
-9 tools spanning EPA facility compliance, toxic chemical releases, Superfund cleanup sites, drinking water safety, environmental justice screening, and real-time air quality:
+EPA environmental data across five federal programs — facility compliance (ECHO), toxic chemical releases (TRI), Superfund cleanup sites, drinking water systems (SDWIS), and environmental-justice screening (EJScreen) — plus real-time air quality via AirNow. Search facilities by location or compliance status, pull inspection and enforcement history, track toxic releases across a region, and screen a point for environmental-justice risk from any MCP client. Runs as a stdio process or a local Streamable HTTP server.
+
+### Tools
 
 | Tool | Description |
 |:---|:---|
-| `epa_search_facilities` | Search EPA-regulated facilities by location (ZIP, state, city, or latitude/longitude + radius proximity), industry, or compliance status across all environmental programs (CAA, CWA, RCRA, TRI, SDWA). Returns facility name, EPA Registry ID, coordinates, county FIPS, per-program compliance flags, inspection counts, penalty totals, and TRI release totals. |
-| `epa_get_facility` | Retrieve a full compliance profile for a single EPA-regulated facility: compliance status per program, inspection dates, formal enforcement actions, penalty amounts, and TRI annual release totals. Aggregates multiple ECHO DFR endpoints in parallel. |
-| `epa_search_violations` | Search EPA civil and criminal enforcement cases by state, regulatory program, or date range. Returns case identifier, facility name and Registry ID, programs involved, penalty assessed, settlement date, and case type. |
-| `epa_get_air_quality` | Get AQI observations or forecasts for a location. Returns per-pollutant AQI values (PM2.5, ozone, CO, SO2, NO2), AQI category (Good through Hazardous), reporting area name, and observation timestamp. |
-| `epa_get_tri_releases` | Query Toxic Release Inventory annual chemical release data for a specific facility by medium (air, water, land, underground injection) and reporting year. |
-| `epa_search_tri_releases` | Search Toxic Release Inventory data across facilities in a state or county for a given year. Returns facility name, TRI ID, chemical name, total releases by medium, and facility coordinates. |
-| `epa_search_superfund` | Search Superfund (CERCLA/SEMS) sites by location or NPL listing status. Accepts state/city/ZIP or lat/lng + radius for proximity searches. Returns site name, EPA ID, NPL status, cleanup status, and coordinates. |
-| `epa_search_water_systems` | Search drinking water systems (SDWIS) by state or ZIP code. Returns system name, PWSID, population served, primary water source, and active violation status. |
-| `epa_get_ejscreen` | Get EJScreen environmental-justice indicators for a point + buffer: 13 environmental and 6 demographic indicators with national/state percentiles, EJ Index values, and the demographic indices. Serves EJScreen v2.2 (2022) via the community-maintained EJAM API (Public Environmental Data Partners), which rehosts EJScreen after EPA discontinued public access in 2025. |
-
-### `epa_search_facilities`
-
-Search for EPA-regulated facilities with cross-program compliance data.
-
-- Geographic filters: ZIP code, state, city (city requires state), or latitude + longitude + radius_miles for proximity search
-- Program filter: narrow to CAA, CWA, RCRA, TRI, or SDWA registrants
-- Compliance filter: `has_violation` flag to surface only non-compliant facilities
-- Returns `RegistryID` (key for `epa_get_facility`), `FacFIPSCode` (county FIPS for Census chaining), and coordinates
-- Results cap enforced — unscoped searches are prohibited at the input validation layer
+| `epa_search_facilities` | Search EPA-regulated facilities by location, industry program, or compliance status across CAA, CWA, RCRA, TRI, and SDWA |
+| `epa_get_facility` | Full compliance profile for one facility by EPA Registry ID — inspections, enforcement actions, and penalties |
+| `epa_search_violations` | Search EPA civil and criminal enforcement cases by state, program, or date range |
+| `epa_get_air_quality` | Current AQI observations or next-day forecasts from AirNow |
+| `epa_get_tri_releases` | Per-chemical Toxic Release Inventory data for a single facility |
+| `epa_search_tri_releases` | Toxic Release Inventory records across facilities in a state or county |
+| `epa_search_superfund` | Search Superfund (CERCLA/SEMS) sites by location or NPL listing status |
+| `epa_search_water_systems` | Search drinking water systems (SDWIS) by state or ZIP code |
+| `epa_get_ejscreen` | EJScreen environmental-justice indicators for a point and buffer |
+
+### Resources
+
+| Resource | Description |
+|:---|:---|
+| `epa://facility/{registry_id}` | Full compliance profile for a facility by EPA Registry ID (same data as `epa_get_facility`) |
+| `epa://superfund/{site_id}` | Superfund site record by SEMS site ID |
 
----
+All resource data is also reachable via tools — use `epa_get_facility` and `epa_search_superfund` for programmatic access in tool-only MCP clients.
 
-### `epa_get_facility`
+## Capability reference
 
-Retrieve a comprehensive compliance profile by EPA Registry ID.
+### `epa_search_facilities` <sub>tool</sub>
 
-- Aggregates 3–5 ECHO DFR endpoints in parallel: program flags and TRI totals, compliance summary, inspection/enforcement history, CAA details (if registered), CWA/NPDES permit details (if registered)
-- Uses `Promise.allSettled` — partial data returned even if one upstream endpoint fails
-- Includes formal enforcement actions, penalty amounts, and inspection dates across all programs
+- Geographic filters: ZIP code, state, city (pair with state), or latitude + longitude + radius_miles (max 100 miles) for proximity search — at least one is required
+- Optional `programs` filter narrows to CAA, CWA, RCRA, TRI, or SDWA registrants; `has_violation` surfaces only non-compliant facilities
+- Returns `registryId` for `epa_get_facility`, plus `fipsCode` when available for Census chaining
+- Up to 100 results per call (default 50)
 
 ---
 
-### `epa_search_violations`
-
-Search area-level EPA enforcement cases — distinct from per-facility history in `epa_get_facility`.
+### `epa_get_facility` <sub>tool</sub>
 
-- Program filter: CAA, CWA, RCRA, SDWA, CERCLA, FIFRA, or TSCA
-- Case type: civil, criminal, or all
-- Date range filtering by filing date (ISO 8601)
-- Returns case identifier, affected facility name and Registry ID for downstream `epa_get_facility` lookup
+- Input: `registry_id`, obtained from `epa_search_facilities`
+- Aggregates 3–5 ECHO DFR endpoints in parallel — program flags and TRI totals, compliance summary, inspection/enforcement history, CAA details, CWA/NPDES permit details
+- Uses `Promise.allSettled` — partial data is returned even when one upstream endpoint fails
+- `airCompliance` / `waterCompliance` are present only when the facility is registered under that program
+- `facility_not_found` when ECHO has no record for the Registry ID
 
 ---
 
-### `epa_get_air_quality`
+### `epa_search_violations` <sub>tool</sub>
 
-Get current AQI observations or daily forecasts from AirNow.
-
-- Accepts ZIP code or latitude/longitude coordinates
-- `mode: current` returns the latest observed AQI per pollutant; `mode: forecast` returns daily AQI forecasts (requires `forecast_date`)
-- AQI categories: Good (1) through Hazardous (6) with numeric and text category
-- Data is preliminary — suitable for awareness, not regulatory or enforcement decisions
-- AirNow responses cached at ~1 hour TTL to respect rate limits
+- At least one of `state` or `zip_code` is required
+- `program` filter covers CAA, CWA, RCRA, SDWA, CERCLA, FIFRA, or TSCA; `case_type` is civil, criminal, or all (default all)
+- Date range filter by filing date (ISO 8601 `date_filed_start` / `date_filed_end`)
+- `facilityName` and `registryId` are not populated by ECHO's enforcement-case endpoint — chain into `epa_get_facility` for facility detail
+- Up to 100 cases per call (default 50)
 
 ---
 
-### `epa_get_tri_releases`
-
-Query per-chemical release breakdown for a single TRI facility.
+### `epa_get_air_quality` <sub>tool</sub>
 
-- Accepts TRI facility ID from `epa_search_facilities` results
-- Returns release quantities by medium: air, water, land, underground injection
-- Optional year filter (defaults to most recent available); optional chemical name filter
-- TRI data lags ~18 months — most recent available year is typically 2 years prior to current
+- Provide `zip_code` or both `latitude` and `longitude`
+- `mode`: `current` (default) or `forecast` (requires `forecast_date`, ISO 8601)
+- Per-pollutant AQI (PM2.5, ozone, CO, SO2, NO2) with numeric `categoryNumber` (1 Good – 6 Hazardous) and `categoryName`
+- `distance_miles` sets the reporting-station search radius (default 25, max 300)
+- Data is preliminary — informational use only, not for regulatory decisions; responses are cached ~1 hour
+- Only registered when `AIRNOW_API_KEY` is set
 
 ---
 
-### `epa_search_tri_releases`
+### `epa_get_tri_releases` <sub>tool</sub>
 
-Identify top polluters in a region via TRI data.
+- `facility_id` is the TRI `facilityId` from `epa_search_tri_releases`; optional `year` (1987–2030, defaults to all available years) and `chemical_name` (partial match)
+- Per-chemical breakdown by medium — air, water, land, underground injection — plus a separate one-time/non-routine release total
+- TRI data lags ~18 months; the most recent available year is typically 2 years prior to the current year
 
-- State and optional county scope; required year parameter
-- Optional chemical name filter to focus on a specific substance
-- Returns facility coordinates for downstream map or proximity analysis
+---
+
+### `epa_search_tri_releases` <sub>tool</sub>
+
+- `state` is required (2-letter); optional `county` (partial match), `year`, and `chemical_name`
+- Up to 200 records per call (default 50); an enrichment flag marks the result truncated when it hits the limit
 - Complement to `epa_get_tri_releases` — use this for area discovery, then drill into a specific facility
 
 ---
 
-### `epa_search_superfund`
-
-Search Superfund (CERCLA/SEMS) sites by location or proximity.
+### `epa_search_superfund` <sub>tool</sub>
 
-- Two input shapes: state/city/ZIP for administrative filters, or lat/lng + radius for proximity
-- NPL status filter: listed, not-listed, proposed, or all
-- Returns site cleanup status and coordinates for downstream spatial analysis
+- Two input shapes: `state`/`city`/`zip_code`, or `latitude`+`longitude`+`radius_miles` (0.1–500 miles) — one is required
+- `npl_status` filter: `listed`, `not-listed`, `proposed`, or `all` (default `all`)
+- Up to 200 sites per call (default 50)
 
 ---
 
-### `epa_search_water_systems`
+### `epa_search_water_systems` <sub>tool</sub>
 
-Identify drinking water systems with active or recent violations.
-
-- State and optional ZIP code scope
-- `has_violation` flag surfaces only systems with current violations
-- PWS type filter: community (`CWS`), non-transient non-community (`NTNCWS`), or transient non-community (`TNCWS`)
+- At least one of `state` or `zip_code` is required
+- `has_violation` surfaces only systems with active violations; `pws_type` filters to `community`, `non-transient`, or `transient` (output `type` reports the SDWIS codes CWS / NTNCWS / TNCWS)
+- Up to 200 systems per call (default 50)
 
 ---
 
-### `epa_get_ejscreen`
+### `epa_get_ejscreen` <sub>tool</sub>
 
-Screen a point and its surrounding buffer for environmental-justice indicators.
+- Input: `latitude`, `longitude`, `distance` (default 1), and `unit` (`miles` or `kilometers`, default `miles`); kilometers are converted to miles before the request, and the buffer is capped at 15 miles
+- Returns 13 environmental and 6 demographic indicators, each with national/state percentiles, plus the Demographic Index and Supplemental Demographic Index
+- Points outside US coverage return `coverage.valid: false` with a note instead of fabricated indicators
+- Data source: EJScreen v2.2 (2022) via the community-maintained EJAM API (Public Environmental Data Partners) — not a live EPA endpoint
 
-- Input: `latitude`, `longitude`, `distance` (default 1), and `unit` (`miles` or `kilometers`); kilometers are converted to miles before the request, and the buffer is capped at 15 miles
-- Returns the 13 EJScreen environmental indicators (PM2.5, ozone, diesel particulate, NO2, lead paint, traffic proximity, Superfund/RMP/hazardous-waste/wastewater proximity, underground storage tanks, drinking-water non-compliance, RSEI toxic air releases) and 6 demographic indicators (people of color, low income, limited English, less than high school, under 5, over 64)
-- Each indicator carries national and state percentiles plus EJ Index values; the Demographic Index and Supplemental Demographic Index are included
-- Points outside US coverage return a coverage note instead of fabricated indicators
-- **Data source:** EJScreen v2.2 (2022) served via the community-maintained [EJAM API](https://api.ejanalysis.com) (Public Environmental Data Partners), which rehosts EJScreen after EPA discontinued public access in 2025 — not a live EPA endpoint
+---
 
-## Resources and prompts
+### `epa://facility/{registry_id}` <sub>resource</sub>
 
-| Type | Name | Description |
-|:---|:---|:---|
-| Resource | `epa://facility/{registry_id}` | Full compliance profile for a facility by EPA Registry ID (same data as `epa_get_facility`) |
-| Resource | `epa://superfund/{site_id}` | Superfund site record by SEMS site ID |
+- Same data as `epa_get_facility`; `registry_id` comes from `epa_search_facilities`
+- Errors when the Registry ID has no ECHO record
 
-All resource data is also reachable via tools. Use `epa_get_facility` and `epa_search_superfund` for programmatic access in tool-only MCP clients.
+---
 
-## Features
+### `epa://superfund/{site_id}` <sub>resource</sub>
 
-Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):
+- Same data as `epa_search_superfund` records; `site_id` comes from `epa_search_superfund`
+- Errors when the site ID has no SEMS record
+
+## Features
 
-- Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
-- Unified error handling — handlers throw, framework catches, classifies, and formats
-- Pluggable auth: `none`, `jwt`, `oauth`
-- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
-- Structured logging with optional OpenTelemetry tracing
-- STDIO and Streamable HTTP transports
+Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
 
 EPA-specific:
 
-- Multiple environmental data sources unified behind a single `epa_` tool surface: ECHO (facility compliance), Envirofacts DMAP (TRI, Superfund, SDWIS), AirNow (real-time air quality), and the community-maintained EJAM API rehosting EJScreen environmental-justice data (v2.2, 2022)
+- Multiple environmental data sources unified behind a single `epa_` tool surface: ECHO (facility compliance), Envirofacts DMAP (TRI, Superfund, SDWIS), AirNow (real-time air quality), and the community-maintained EJAM API rehosting EJScreen data (v2.2, 2022)
 - Parallel ECHO DFR aggregation in `epa_get_facility` — 3–5 upstream calls resolved concurrently with `Promise.allSettled`
 - AirNow response caching (~1 hour TTL) to stay within per-key rate limits
-- DMAP coordinate normalization — `tri.tri_facility` DDMMSS integers converted to decimal degrees
 
 Agent-friendly output:
 
-- Cross-tool join keys surfaced on every response — `RegistryID` and `FacFIPSCode` from facility search feed directly into compliance, TRI, and Census API workflows
-- Typed enforcement and compliance status fields — agents branch on data values, not string parsing
-- Structured partial failure — `epa_get_facility` returns available program data even when one DFR endpoint is unavailable, with per-section status
+- Facility search supplies `registryId` for compliance lookups and `fipsCode` when available for Census queries; TRI search supplies `facilityId` for release details
+- Structured partial failure — `epa_get_facility` returns available program data even when one DFR endpoint is unavailable, with `airCompliance`/`waterCompliance` present only when that program applies
+- Recovery-hint messages on empty results — every search tool returns a `message` field that echoes the applied filters and suggests how to broaden the search
 
 ## Getting started
 
@@ -207,6 +199,25 @@ Or with npx (no Bun required):
 }
 ```
 
+Or with Docker:
+
+```json
+{
+  "mcpServers": {
+    "epa-mcp-server": {
+      "type": "stdio",
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "MCP_TRANSPORT_TYPE=stdio",
+        "-e", "AIRNOW_API_KEY=your-airnow-key",
+        "ghcr.io/cyanheads/epa-mcp-server:latest"
+      ]
+    }
+  }
+}
+```
+
 For Streamable HTTP, set the transport and start the server:
 
 ```sh
@@ -216,7 +227,7 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 AIRNOW_API_KEY=... bun run start:http
 
 ### Prerequisites
 
-- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).
+- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
 - (Optional) An AirNow API key to enable `epa_get_air_quality` — register free at [docs.airnowapi.org/account/request](https://docs.airnowapi.org/account/request/). Without it the server runs the other 8 tools. ECHO, DMAP, and EJScreen tools require no API key.
 
 ### Installation
@@ -260,6 +271,7 @@ All configuration is validated at startup via Zod schemas in `src/config/`. Key
 | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http` | `stdio` |
 | `MCP_HTTP_PORT` | HTTP server port | `3010` |
 | `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path | `/mcp` |
+| `MCP_SESSION_MODE` | HTTP sessions: `auto`, `stateful`, or `stateless`. Explicit environment values override the server default; `auto` resolves to `stateful`. Tenant-scoped caching is independent of sessions. | `stateless` |
 | `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth` | `none` |
 | `MCP_LOG_LEVEL` | Log level (RFC 5424) | `info` |
 | `LOGS_DIR` | Directory for log files (Node.js only) | `<project-root>/logs` |
@@ -327,7 +339,7 @@ See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rule
 
 ## Contributing
 
-Issues and pull requests are welcome. Run checks and tests before submitting:
+Issues are welcome. Run checks and tests before submitting:
 
 ```sh
 bun run devcheck

package/changelog/0.3.x/0.3.1.md

@@ -0,0 +1,27 @@
+---
+summary: "Modern MCP protocol support and bounded EPA search pagination."
+breaking: false
+security: false
+---
+
+# 0.3.1 — 2026-08-22
+
+## Changed
+
+- **MCP protocol** — adopts `@cyanheads/mcp-ts-core` ^0.12.3 and MCP SDK v2: modern MCP protocol support, undeclared tool input fields are rejected, and error results advertise a validation-compatible envelope.
+- **Packaging** — updates the Bun build images and package manager pin to 1.4.0, and removes platform-specific native bindings from MCPB bundles.
+
+## Fixed
+
+- **`epa_search_tri_releases`** batches facility IDs to avoid oversized URLs and respects `limit`.
+- **`epa_search_violations`, `epa_search_facilities`, and `epa_search_water_systems`** honor `limit` while preserving full-match totals where the upstream exposes them.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.10.14 → ^0.12.3
+- `@biomejs/biome` ^2.5.2 → ^2.5.9
+- `@types/node` ^25.9.3 → ^26.2.0
+- `ignore` ^7.0.5 → ^7.0.6
+- `tsc-alias` ^1.8.17 → ^1.9.2
+- `typescript` ^6.0.3 → ^7.0.2
+- `vitest` ^4.1.9 → ^4.1.11

package/changelog/0.3.x/0.3.2.md

@@ -0,0 +1,40 @@
+---
+summary: "Stateless HTTP defaults, private upstream errors, and mcp-ts-core 0.13.6 adoption."
+breaking: true
+security: true
+agent-notes: |
+  Bun 1.4 or later is required. Development workflows now live under
+  framework-skills/ rather than skills/.
+---
+
+# 0.3.2 — 2026-09-19
+
+## Changed
+
+- HTTP defaults to stateless when MCP_SESSION_MODE is unset; an explicit environment value still overrides it (#22).
+- **Environment configuration** treats empty and whole-placeholder values as unset through `@cyanheads/mcp-ts-core`, so optional AirNow configuration stays disabled and the EJScreen endpoint uses its default.
+- **Runtime baseline** now requires Bun 1.4 or later; this is a runtime migration with unchanged tool contracts.
+- **Tool arguments** accept case-style aliases for declared keys and ignore the framework's fixed client metadata-key list; other unknown keys still return `InvalidParams`.
+- **Error responses** include reason and retryability terms when available and preserve recovery guidance for client-side branching.
+- **Development workflows** moved from `skills/` to `framework-skills/`, and package, bundle, and manifest checks follow the current framework delivery rules.
+- **Project documentation and issue forms** now describe the resource surface, reporting route, security advisory path, and current runtime values.
+
+## Fixed
+
+- **AirNow, ECHO, DMAP, and EJAM failures** no longer expose upstream request URLs in MCP error data. [#23](https://github.com/cyanheads/epa-mcp-server/issues/23)
+- **Invalid tool arguments** now use the framework's production `InvalidParams` error envelope with structured error content.
+- **EJAM non-400 HTTP failures** now use the framework's upstream HTTP classification, while invalid coordinates retain their validation error.
+
+## Security
+
+- **AirNow error handling** no longer returns a credential-bearing upstream URL to clients. [#23](https://github.com/cyanheads/epa-mcp-server/issues/23)
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` `^0.12.3` → `^0.13.6`
+- `zod` `^4.4.3` → `^4.6.5`
+- `@biomejs/biome` `^2.5.9` → `^2.5.14`
+- `@types/node` `^26.2.0` → `^26.6.1`
+- `ignore` `^7.0.6` → `^7.0.9`
+- `tsc-alias` `^1.9.2` → `^1.9.5`
+- `vitest` `^4.1.11` → `^5.0.1`

package/changelog/template.md

@@ -4,10 +4,11 @@
 # to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
 # with a concrete date.
 
-# Required. One-line GitHub Release-style headline. 350 character cap.
-# Default short and scannable. Don't pad, don't stitch unrelated changes with
-# semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
-# inside the value as a key separator and fails GitHub's strict parser.
+# Required. One-line GitHub Release-style headline. 350 character cap — a
+# ceiling, not a target. Default short and scannable. Don't pad, don't stitch
+# unrelated changes with commas/semicolons into an inventory — pick the one
+# headline the release is about. Quotes required: unquoted YAML treats
+# `: ` inside the value as a key separator and fails GitHub's strict parser.
 summary: ""
 
 # Set `true` when consumers must change code to upgrade: API removals,
@@ -15,16 +16,19 @@ summary: ""
 # usage. Flagged as `Breaking` in the rollup.
 breaking: false
 
-# Set `true` if this release contains any security fix. Pairs with the
-# `## Security` section below. Flagged as `Security` in the rollup so
-# users can triage upgrade urgency at a glance.
+# Set `true` ONLY for a security fix in THIS project's own source code — a
+# vulnerability or hardening in code you ship. A dependency or transitive CVE
+# bump is routine maintenance, NOT a security release: record it under
+# `## Dependencies` (with the advisory ID) and leave this `false`. When true,
+# pairs with the `## Security` section below and flags `Security` in the rollup.
 security: false
 
 # Optional free-form notes for maintenance agents processing this release.
 # Not rendered in CHANGELOG — consumed by agents running `maintenance` on
-# downstream servers. Use for adoption instructions that don't fit the
-# human-facing sections: new files to create, fields to populate, one-time
-# migration steps. Omit the field entirely when there's nothing to say.
+# downstream servers. ADOPTION STEPS ONLY — new files to create, fields to
+# populate, one-time migration steps. Never a second rendering of the body:
+# if a body bullet already says it, name the bullet's symbol instead of
+# re-explaining. Omit the field entirely when there's nothing to say.
 # agent-notes: |
 #   <instructions for downstream maintenance agents>
 ---
@@ -39,17 +43,54 @@ security: false
   each bullet with the symbol or concept name in **bold** so they can skip
   what's irrelevant and zoom in on what's not.
 
-  Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
-  name the symbol, state what changed, stop. Use a second sentence only when
-  it carries weight. If a bullet feels long, it is.
-
-  Cut: mechanism walkthroughs (those belong in JSDoc, CLAUDE.md/AGENTS.md, or the
-  relevant skill), ceremonial framings ("This release introduces…",
-  backwards-compat paragraphs), file-by-file test enumerations, internal
-  implementation notes. Prefer code/symbol names over English re-explanations.
+  Tone: terse, fact-dense, not verbose. Bullet shape: **symbol** + what
+  changed + at most one consumer-facing caveat. One sentence by default, two
+  when the second carries weight — a bullet past ~40 words or three sentences
+  is wrong. The depth lives one hop away: the linked issue carries the why,
+  the commit diff carries the how. The changelog names what changed and what
+  a consumer does about it; a reader who wants mechanism opens the link.
+
+  Model length on THIS guide, never on the previous entry — entries modeled
+  on entries compound.
+
+  Cut (each has shipped as a wall of text; these are the cruft):
+  - History/justification narration — how the bug worked, why the old
+    behavior was wrong. One short clause at most; the issue carries the story.
+  - Design-rationale defense — "chosen over Y because…", "guarding the
+    getter is not enough…". That is the author arguing with a reviewer;
+    reviewers read the PR, not the changelog.
+  - Defensive unchanged-clauses — "X is unchanged", "byte-identical to
+    <prev>". Keep one only where its absence would cause a real misread,
+    as a short parenthetical.
+  - Edge-case inventories — marker lists, not-flagged lists, escape tables.
+    Tests and the issue carry those.
+  - Mechanism walkthroughs (JSDoc, CLAUDE.md/AGENTS.md, or the relevant
+    skill own those), ceremonial framings ("This release introduces…"),
+    backwards-compat paragraphs, file-by-file test enumerations. Prefer
+    code/symbol names over English re-explanations.
+
+  Verified ≠ included: the every-claim-verified-from-the-diff rule bounds
+  the TRUTH of what you write, never the AMOUNT.
+
+  Example — same fact, right size:
+
+    TOO LONG: **`fetchWithTimeout`'s `timeoutMs` bounds the whole exchange**
+    (#341). `fetch` resolves once headers arrive and the deadline was
+    cleared as the helper returned, so a peer that answered promptly and
+    then stalled the stream held the request open indefinitely. A 2xx
+    carrying a body now comes back as a passthrough wrapper that disarms
+    the deadline when the body closes, errors, or is cancelled; …
+    [+90 more words of mechanism and edge cases]
+
+    RIGHT: **`fetchWithTimeout`'s `timeoutMs` now bounds the whole
+    exchange, not just the headers** (#341). A stalled body aborts with
+    the same `Timeout` error; the returned `Response` is a wrapper, so
+    identity assertions (`toBe(response)`) no longer hold.
 
   Narrative intro: skip by default. Add one short sentence only when the
-  release theme genuinely needs framing the bullets can't carry.
+  release theme genuinely needs framing the bullets can't carry. When many
+  bullets share one upgrade consequence, state it ONCE — intro line or
+  agent-notes — never per bullet.
 
   Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
   Fixed, Security. Include only sections with entries; delete the rest
@@ -76,30 +117,13 @@ security: false
   in that unrelated item's metadata.
 
   TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
-  via `gh release create --notes-from-tag`. The tag is a derivative of this
-  changelog entry — a condensed, scannable version, not a copy. Format:
-
-    <theme — omit version number, GitHub prepends it>
-                                                          ← blank line
-    <1-2 sentence context: what this release does>
-                                                          ← blank line
-    Dependency bumps:                                     ← section header
-                                                          ← blank line
-    - `@cyanheads/mcp-ts-core` ^0.9.1 → ^0.9.6          ← bullet
-                                                          ← blank line
-    Changed:                                              ← only sections with entries
-                                                          ← blank line
-    - `format()` output includes `query` in text mode
-                                                          ← blank line
-    Added:
-                                                          ← blank line
-    - `manifest.json` scaffolded for MCPB bundle support
-    - Install badges (Claude Desktop, Cursor, VS Code)
-                                                          ← blank line
-    <N> tests pass; `bun run devcheck` clean.             ← footer
-
-  Never a flat comma-separated string. Always structured markdown with
-  sections. The tag must scan well as a rendered GitHub Release page.
+  via `gh release create --notes-from-tag`. It is a condensed digest of this
+  entry, never a copy, and its format is owned by the `release-and-publish`
+  skill (step 4, "Create the annotated tag"): a short subject line without the
+  version, flat headline bullets — no Keep-a-Changelog section headers, no
+  gates line — at most one deps line, issue backlinks, and the changelog link
+  last. In release-PR mode the `git-wrapup` skill authors those bullets as the
+  PR body's `## Changes` and the tag copies them.
 -->
 
 ## Added

package/dist/config/server-config.d.ts

@@ -4,11 +4,11 @@
  */
 import { z } from '@cyanheads/mcp-ts-core';
 declare const ServerConfigSchema: z.ZodObject<{
-    airNowApiKey: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+    airNowApiKey: z.ZodOptional<z.ZodString>;
     echoBaseUrl: z.ZodDefault<z.ZodString>;
     dmapBaseUrl: z.ZodDefault<z.ZodString>;
     airNowBaseUrl: z.ZodDefault<z.ZodString>;
-    ejscreenBaseUrl: z.ZodPreprocess<z.ZodDefault<z.ZodString>>;
+    ejscreenBaseUrl: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
 export type ServerConfig = z.infer<typeof ServerConfigSchema>;
 export declare function getServerConfig(): ServerConfig;

package/dist/config/server-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;;;iBAoCtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAS9C"}
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;;;iBA4BtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAS9C"}

package/dist/config/server-config.js

@@ -5,11 +5,10 @@
 import { z } from '@cyanheads/mcp-ts-core';
 import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
 const ServerConfigSchema = z.object({
-    // Optional: an empty or whitespace-only value (e.g. an unfilled `${AIRNOW_API_KEY}`
-    // placeholder from a bundle/compose config) is treated as absent so the server still
-    // starts. When absent, index.ts skips registering epa_get_air_quality and AirNow init.
     airNowApiKey: z
-        .preprocess((v) => (typeof v === 'string' && v.trim() === '' ? undefined : v), z.string().min(1).optional())
+        .string()
+        .min(1)
+        .optional()
         .describe('AirNow API key (free registration at docs.airnowapi.org). Optional — when unset, epa_get_air_quality is not registered and the other tools run without it.'),
     echoBaseUrl: z
         .string()
@@ -26,11 +25,10 @@ const ServerConfigSchema = z.object({
         .url()
         .default('https://www.airnowapi.org/aq')
         .describe('AirNow API base URL'),
-    // Optional override. Bundle/compose configs may inject an unfilled
-    // `${EJSCREEN_API_BASE_URL}` placeholder as an empty string — treat empty or
-    // whitespace-only as absent so the default applies instead of failing `.url()`.
     ejscreenBaseUrl: z
-        .preprocess((v) => (typeof v === 'string' && v.trim() === '' ? undefined : v), z.string().url().default('https://api.ejanalysis.com'))
+        .string()
+        .url()
+        .default('https://api.ejanalysis.com')
         .describe('EJScreen (EJAM) API base URL — the community-maintained EJScreen rehost'),
 });
 let _config;

package/dist/config/server-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,oFAAoF;IACpF,qFAAqF;IACrF,uFAAuF;IACvF,YAAY,EAAE,CAAC;SACZ,UAAU,CACT,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,EACjE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAC7B;SACA,QAAQ,CACP,4JAA4J,CAC7J;IACH,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,+BAA+B,CAAC;SACxC,QAAQ,CAAC,mBAAmB,CAAC;IAChC,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,kCAAkC,CAAC;SAC3C,QAAQ,CAAC,mBAAmB,CAAC;IAChC,aAAa,EAAE,CAAC;SACb,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,8BAA8B,CAAC;SACvC,QAAQ,CAAC,qBAAqB,CAAC;IAClC,mEAAmE;IACnE,6EAA6E;IAC7E,gFAAgF;IAChF,eAAe,EAAE,CAAC;SACf,UAAU,CACT,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,EACjE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,4BAA4B,CAAC,CACvD;SACA,QAAQ,CAAC,yEAAyE,CAAC;CACvF,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,YAAY,EAAE,gBAAgB;QAC9B,WAAW,EAAE,mBAAmB;QAChC,WAAW,EAAE,mBAAmB;QAChC,aAAa,EAAE,qBAAqB;QACpC,eAAe,EAAE,uBAAuB;KACzC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,YAAY,EAAE,CAAC;SACZ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,QAAQ,CACP,4JAA4J,CAC7J;IACH,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,+BAA+B,CAAC;SACxC,QAAQ,CAAC,mBAAmB,CAAC;IAChC,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,kCAAkC,CAAC;SAC3C,QAAQ,CAAC,mBAAmB,CAAC;IAChC,aAAa,EAAE,CAAC;SACb,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,8BAA8B,CAAC;SACvC,QAAQ,CAAC,qBAAqB,CAAC;IAClC,eAAe,EAAE,CAAC;SACf,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,4BAA4B,CAAC;SACrC,QAAQ,CAAC,yEAAyE,CAAC;CACvF,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,YAAY,EAAE,gBAAgB;QAC9B,WAAW,EAAE,mBAAmB;QAChC,WAAW,EAAE,mBAAmB;QAChC,aAAa,EAAE,qBAAqB;QACpC,eAAe,EAAE,uBAAuB;KACzC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}