@cyanheads/epa-mcp-server 0.3.1 → 0.3.3

package/Dockerfile

@@ -4,11 +4,17 @@
 # This stage installs all dependencies (including dev), builds the TypeScript
 # source code into JavaScript, and prepares the production assets.
 #
-# The build emits platform-independent JavaScript, so pin it to the native
-# BuildKit platform. Bun's JavaScriptCore does not run reliably under QEMU
-# during cross-architecture builds.
+# Pinned to $BUILDPLATFORM rather than the target platform: `bun run build` emits
+# JavaScript, and only `dist/` crosses into the production stage. Built for the
+# target instead, the non-native leg of a `--platform linux/amd64,linux/arm64`
+# build runs under QEMU, where bun >= 1.4 aborts with a JavaScriptCore allocator
+# assertion and fails the multi-arch push.
+#
+# The constraint this assumes: the build stage produces platform-independent
+# output. A stage that compiles a native addon needs the target-arch toolchain
+# and cannot cross-compile this way — drop the flag there.
 # ==============================================================================
-FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS build
 
 WORKDIR /usr/src/app
 
@@ -27,19 +33,92 @@ COPY . .
 RUN bun run build
 
 
+# ==============================================================================
+# Production Dependencies Stage
+#
+# Installs the production dependency tree for the target platform. Every step
+# here can run JavaScript — bunfig.toml's security scanner runs as a Bun
+# program, and so do the OTel and musl-prune scripts — so the stage runs on
+# $BUILDPLATFORM and cross-installs with `--os`/`--cpu`, which pick each
+# platform-specific optional dependency (native bindings such as DuckDB's) for
+# the target. Only `node_modules` leaves this stage.
+#
+# A clean image rather than `FROM build`: the build stage's node_modules holds
+# devDependencies.
+# ==============================================================================
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS deps
+
+WORKDIR /usr/src/app
+
+# Copy dependency manifests. `bunfig.toml` rides along so every install below
+# passes its release-age gate and security scanner, as a local install does.
+COPY package.json bun.lock bunfig.toml ./
+
+# The scanner bunfig.toml names is a devDependency, and Bun installs a missing
+# scanner through the same production-filtered install, which omits it and
+# aborts. Seed it from the build stage's full install instead. Remove this line,
+# and the `rm` at the end of this stage, if bunfig.toml stops naming a scanner.
+COPY --from=build /usr/src/app/node_modules/@socketsecurity/bun-security-scanner ./node_modules/@socketsecurity/bun-security-scanner
+
+# Docker names the target architecture `amd64`/`arm64`; Bun's `--cpu` takes
+# `x64`/`arm64`. Mapped once here, read by both installs below. `oven/bun`
+# publishes only these two architectures, so any other target fails here.
+ARG TARGETOS
+ARG TARGETARCH
+RUN case "$TARGETARCH" in \
+      amd64) echo x64 ;; \
+      arm64) echo arm64 ;; \
+      *) echo "Unsupported TARGETARCH '$TARGETARCH': expected amd64 or arm64" >&2; exit 1 ;; \
+    esac > .bun-cpu
+
+# Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
+# that are not needed in the final production image.
+# `--omit=peer` drops the framework's optional peer tiers (test runner, service
+# SDKs, parsers) that Bun would otherwise auto-install. Anything this server
+# actually imports belongs in its own `dependencies`, so nothing needed at
+# runtime is lost.
+RUN --mount=type=cache,target=/root/.bun/install/cache \
+    bun install --production --omit=peer --frozen-lockfile --ignore-scripts \
+      --os="$TARGETOS" --cpu="$(cat .bun-cpu)"
+
+# Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
+# Installed by default. Omit them for a leaner image at build time
+# with: docker build --build-arg OTEL_ENABLED=false
+# The script reads the list and each range from the installed framework's
+# `peerDependencies` and passes the target flags on to its `bun install`.
+COPY scripts/install-otel.ts ./scripts/
+ARG OTEL_ENABLED=true
+RUN --mount=type=cache,target=/root/.bun/install/cache \
+    if [ "$OTEL_ENABLED" = "true" ]; then \
+      bun scripts/install-otel.ts --os="$TARGETOS" --cpu="$(cat .bun-cpu)"; \
+    fi
+
+# `--os`/`--cpu` have no libc counterpart, so a native dependency published in
+# glibc and musl variants (DuckDB's bindings, for one) installs both. The
+# runtime image is Debian (glibc) and never loads the musl copy; the script
+# deletes every package whose own `libc` admits only musl. It follows every
+# install, since a later `bun install` restores what it removes. A server on a
+# musl (Alpine) runtime image drops these two lines.
+COPY scripts/prune-musl-packages.ts ./scripts/
+RUN bun scripts/prune-musl-packages.ts
+
+# The seeded scanner served only the installs above; keep it out of the image.
+RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
+
+
 # ==============================================================================
 # Production Stage
 #
 # This stage creates a minimal, optimized, and secure image for running the
 # application. It uses a slim base image and only includes production
-# dependencies and build artifacts.
+# dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
+# and CMD, which run on the real target at container start.
 # ==============================================================================
-FROM oven/bun:1.4.0-slim AS production
+FROM oven/bun:1.4.2-slim AS production
 
 WORKDIR /usr/src/app
 
-# Set the environment to production for performance and to ensure only
-# production dependencies are installed.
+# Set the environment to production for performance.
 ENV NODE_ENV=production
 
 # OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
@@ -50,44 +129,37 @@ LABEL org.opencontainers.image.licenses="Apache-2.0"
 LABEL org.opencontainers.image.version="${APP_VERSION}"
 LABEL org.opencontainers.image.source="https://github.com/cyanheads/epa-mcp-server"
 
-# Copy dependency manifests
-COPY package.json bun.lock ./
-
-# Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
-# that are not needed in the final production image.
-# `--omit=peer` drops the framework's optional peer tiers that Bun would
-# otherwise auto-install. The OTEL step below carries the same flag so that
-# install does not re-resolve the optional peer graph.
-RUN --mount=type=cache,target=/root/.bun/install/cache \
-    bun install --production --omit=peer --frozen-lockfile --ignore-scripts
-
-# Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
-# These are not bundled by default to keep the base image lean. Enable at build time
-# with: docker build --build-arg OTEL_ENABLED=true
-ARG OTEL_ENABLED=true
-RUN --mount=type=cache,target=/root/.bun/install/cache \
-    if [ "$OTEL_ENABLED" = "true" ]; then \
-      bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
-        @opentelemetry/instrumentation-http \
-        @opentelemetry/exporter-metrics-otlp-http \
-        @opentelemetry/exporter-trace-otlp-http \
-        @opentelemetry/instrumentation-pino \
-        @opentelemetry/resources \
-        @opentelemetry/sdk-metrics \
-        @opentelemetry/sdk-node \
-        @opentelemetry/sdk-trace-node \
-        @opentelemetry/semantic-conventions; \
-    fi
+# The manifest comes from the build context: the deps stage's copy was rewritten
+# by the OTel install, and the runtime reads only its name, version, and type.
+COPY package.json ./
+COPY --from=deps /usr/src/app/node_modules ./node_modules
 
 # Copy the compiled application code from the build stage
 COPY --from=build /usr/src/app/dist ./dist
 
+# Mirror CLI (MirrorService adopters only — Tier 3, opt-in):
+# Copy your mirror lifecycle scripts and emit a runtime tsconfig so Bun resolves
+# the @/ path alias against ./dist/ rather than ./src/.
+# See the api-mirror skill for the full recipe.
+#
+# COPY --from=build /usr/src/app/scripts/<your>-mirror-init.ts \
+#                   /usr/src/app/scripts/<your>-mirror-refresh.ts \
+#                   /usr/src/app/scripts/<your>-mirror-verify.ts \
+#                   /usr/src/app/scripts/_mirror-context.ts \
+#                   ./scripts/
+# RUN echo '{"compilerOptions":{"baseUrl":".","paths":{"@/*":["./dist/*"]}}}' > tsconfig.json
+
 # The 'oven/bun' image already provides a non-root user named 'bun'.
 # We will use this existing user for enhanced security.
 
 # Create and set permissions for the log directory, assigning ownership to the 'bun' user.
 RUN mkdir -p /var/log/epa-mcp-server && chown -R bun:bun /var/log/epa-mcp-server
 
+# Writable data dirs for on-disk SQLite stores (catalog index / observations
+# mirror), owned by the runtime user. Mount a volume over either in production.
+RUN mkdir -p /usr/src/app/.cache /usr/src/app/.mirror \
+  && chown -R bun:bun /usr/src/app/.cache /usr/src/app/.mirror
+
 # Switch to the non-root user
 USER bun
 
@@ -103,7 +175,6 @@ ENV MCP_TRANSPORT_TYPE="http"
 ENV MCP_SESSION_MODE="stateless"
 ENV MCP_LOG_LEVEL="info"
 ENV LOGS_DIR="/var/log/epa-mcp-server"
-ENV MCP_FORCE_CONSOLE_LOGGING="true"
 
 # Expose the port the server listens on
 EXPOSE ${MCP_HTTP_PORT}

package/README.md

@@ -1,13 +1,13 @@
 <div align="center">
   <h1>@cyanheads/epa-mcp-server</h1>
   <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>
-  <div>9 Tools • 2 Resources</div>
   </p>
+  <div>9 Tools • 2 Resources</div>
 </div>
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.3.1-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/)
+[![Version](https://img.shields.io/badge/Version-0.3.3-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.2.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.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -21,151 +21,131 @@
 
 ---
 
-## 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
+- Provide ZIP code, state, city (preferably with state), or latitude + longitude + radius_miles (max 100 miles); up to 100 results (default 50)
+- Returns `registryId` for `epa_get_facility`, plus `fipsCode` when available for Census queries
+- `programs` filters CAA, CWA, RCRA, TRI, or SDWA; `has_violation` filters significant violations
 
 ---
 
-### `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
+- `registry_id` comes from `epa_search_facilities`
+- Returns compliance, inspections, enforcement actions, penalties, and TRI totals; available program data survives partial upstream failures
+- `airCompliance` / `waterCompliance` appear only for registered programs; `facility_not_found` identifies a missing record
 
 ---
 
-### `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
+- Requires `state` or `zip_code`; up to 100 cases (default 50)
+- `program` filters CAA, CWA, RCRA, SDWA, CERCLA, FIFRA, or TSCA; `case_type` is civil, criminal, or all (default); `date_filed_start` / `date_filed_end` filter ISO dates
+- `facilityName` and `registryId` are unavailable from this endpoint; discover facilities with `epa_search_facilities`
 
 ---
 
-### `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` is current (default) or forecast (requires ISO `forecast_date`); `distance_miles` defaults to 25, max 300
+- Returns per-pollutant AQI, `categoryNumber` (1 Good–6 Hazardous), and `categoryName`; preliminary data is unsuitable for regulatory, trend, or enforcement decisions
+- Registered only when `AIRNOW_API_KEY` is set; responses cache for about one hour
 
 ---
 
-### `epa_search_tri_releases`
+### `epa_get_tri_releases` <sub>tool</sub>
 
-Identify top polluters in a region via TRI data.
-
-- 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
-- Complement to `epa_get_tri_releases` — use this for area discovery, then drill into a specific facility
+- `facility_id` is the TRI `facilityId` from `epa_search_tri_releases`; optional `year` (1987–2030, all available by default) and partial `chemical_name`
+- Returns per-chemical air, water, land, and underground-injection releases, plus a separate one-time/non-routine total
 
 ---
 
-### `epa_search_superfund`
-
-Search Superfund (CERCLA/SEMS) sites by location or proximity.
+### `epa_search_tri_releases` <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
+- Requires 2-letter `state`; optional partial `county`, `chemical_name`, and `year`; up to 200 records (default 50)
+- Returns `facilityId` for `epa_get_tri_releases`; enrichment marks results truncated when the limit is reached
 
 ---
 
-### `epa_search_water_systems`
+### `epa_search_superfund` <sub>tool</sub>
 
-Identify drinking water systems with active or recent violations.
+- Provide `state`/`city`/`zip_code`, or `latitude` + `longitude` + `radius_miles` (0.1–500); up to 200 sites (default 50)
+- Returns site identifiers, location, NPL, and cleanup status; `npl_status` filters listed, not-listed, proposed, or all (default)
+
+---
 
-- 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`)
+### `epa_search_water_systems` <sub>tool</sub>
+
+- Requires `state` or `zip_code`; up to 200 systems (default 50)
+- `has_violation` filters active violations; `pws_type` is community, non-transient, or transient, returned as CWS / NTNCWS / TNCWS in `type`
 
 ---
 
-### `epa_get_ejscreen`
+### `epa_get_ejscreen` <sub>tool</sub>
 
-Screen a point and its surrounding buffer for environmental-justice indicators.
+- Requires `latitude` and `longitude`; `distance` defaults to 1, `unit` to miles (kilometers accepted); buffer capped at 15 miles
+- Returns 13 environmental and 6 demographic indicators with national/state percentiles and demographic indices; outside coverage, `coverage.valid: false` carries a note
+- EJScreen v2.2 (2022) comes from the community-maintained EJAM API (Public Environmental Data Partners)
 
-- 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 |
+- `registry_id` comes from `epa_search_facilities`
+- Returns the `epa_get_facility` compliance profile; errors when no facility resolves
 
-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):
+- `site_id` comes from `epa_search_superfund`
+- Returns the Superfund site record; errors when no SEMS record resolves
+
+## 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
+- TRI reporting lags about 18 months; the latest available reporting year is typically two years behind
 
 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 +187,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 +215,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+); development and Docker use Bun v1.4.2.
 - (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,11 +259,17 @@ 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` |
+| `LOG_TOOL_FAILURE_PAYLOADS` | Log failed calls' arguments and results with key-name redaction. Secrets inside free-form values remain visible. | `false` |
+| `LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES` | UTF-8 byte cap per logged payload. | `16384` |
 | `LOGS_DIR` | Directory for log files (Node.js only) | `<project-root>/logs` |
 | `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1` | `in-memory` |
 | `OTEL_ENABLED` | Enable [OpenTelemetry](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) tracing and metrics | `false` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP base URL; traces use `/v1/traces`, metrics `/v1/metrics`. | — |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Signal-specific endpoint overrides, used as-is. | — |
+| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Enables OTLP log export; the base endpoint alone does not enable it. | — |
 
 See [`.env.example`](./.env.example) for the full list of optional overrides.
 
@@ -327,7 +332,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.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/0.3.x/0.3.3.md

@@ -0,0 +1,34 @@
+---
+summary: "ECHO debug logs use endpoint labels instead of request URLs, with framework recovery and error privacy updates."
+breaking: false
+security: true
+---
+
+# 0.3.3 — 2026-10-07
+
+## Changed
+
+- **Domain recovery** uses the framework's declared-hint fill from 0.13.10; redundant forwards are removed and contract tests preserve hints on both MCP result surfaces.
+- **Framework input and errors** adopt 0.13.9's integer-to-string repair and field-path guidance, 0.13.10's error request IDs, 0.13.12's generated IDs and URL-origin redaction, and 0.13.13's removal of framework-added `rootCause` from error envelopes.
+- **Docker builds** use Bun 1.4.2 and a native build-platform dependency stage, cross-installing for amd64/arm64 with framework-range OTel peers and pruning musl-only bindings.
+- **Framework tooling and guides** are synchronized; configuration documents OTLP endpoints and opt-in failed-call payload logging, packaging excludes `.mcpb`, cache, and logs, and CodeQL uploads per-language categories.
+- **ECHO User-Agent** reports the current server version.
+
+## Fixed
+
+- **MCP Registry npm entries** launch with `npx`, drop npm-script arguments, and fix `MCP_TRANSPORT_TYPE=http` for the HTTP entry.
+
+## Security
+
+- **ECHO debug logs** identify facility and enforcement requests by fixed endpoint labels and query IDs, omitting full configured URL paths and query strings ([#26](https://github.com/cyanheads/epa-mcp-server/issues/26)).
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.6 → ^0.13.13.
+- Dev: `@biomejs/biome` ^2.5.14 → ^2.5.15.
+- Dev: `@socketsecurity/bun-security-scanner` ^1.1.2 → ^1.1.3.
+- Dev: `@types/node` ^26.6.1 → ^26.6.4.
+- Dev: `ignore` ^7.0.9 → ^7.0.12.
+- Dev: `tsc-alias` ^1.9.5 → ^1.9.7.
+- Dev: `vitest` ^5.0.1 → ^5.0.3.
+- **Bun** 1.4.0 → 1.4.2 in `packageManager` and Docker base images.

package/changelog/template.md

@@ -6,8 +6,8 @@
 
 # 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
-# headline, like a tag's theme line. Quotes required: unquoted YAML treats
+# 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: ""
 
@@ -117,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