@cyanheads/epa-mcp-server 0.3.3 → 0.4.1

package/dist/mcp-server/tools/definitions/search-water-systems.tool.js

@@ -7,15 +7,18 @@ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { getDmapService } from '../../../services/dmap/dmap-service.js';
 export const searchWaterSystemsTool = tool('epa_search_water_systems', {
     title: 'Search Drinking Water Systems',
-    description: 'Search drinking water systems (SDWIS) by state or ZIP code. Returns system name, PWSID, population served, primary water source, and active violation status. Use to identify community water systems with current or recent compliance violations. At least one of state or zip_code is required.',
+    description: 'Search drinking water systems (SDWIS) by state or ZIP code. Returns system name, PWSID, population served, primary water source, and activity status. With has_violation, returns only systems with an open violation — one SDWIS has not marked returned to compliance or closed out when the system was deactivated. At least one of state or zip_code is required.',
     annotations: { readOnlyHint: true, openWorldHint: true, idempotentHint: true },
     input: z.object({
         state: z.string().optional().describe('2-letter US state abbreviation (e.g. "WA", "CA")'),
-        zip_code: z.string().optional().describe('5-digit ZIP code to search within'),
+        zip_code: z
+            .string()
+            .optional()
+            .describe("5-digit ZIP code of the water system's address of record — often its owner's or operator's office, which can be far from the area the system serves"),
         has_violation: z
             .boolean()
             .optional()
-            .describe('When true, return only systems with active violations'),
+            .describe('When true, return only systems with an open SDWIS violation (not yet returned to compliance). Works with state, zip_code, or both.'),
         pws_type: z
             .enum(['community', 'non-transient', 'transient'])
             .optional()
@@ -38,8 +41,14 @@ export const searchWaterSystemsTool = tool('epa_search_water_systems', {
                 .string()
                 .optional()
                 .describe('2-letter state abbreviation (primacy agency code)'),
-            city: z.string().optional().describe('City served by this water system'),
-            zip: z.string().optional().describe('ZIP code'),
+            city: z
+                .string()
+                .optional()
+                .describe("City of the water system's address of record — often its owner's or operator's office, not necessarily the area it serves"),
+            zip: z
+                .string()
+                .optional()
+                .describe("ZIP code of the water system's address of record (the value zip_code matches)"),
             type: z
                 .string()
                 .optional()
@@ -55,7 +64,7 @@ export const searchWaterSystemsTool = tool('epa_search_water_systems', {
             hasViolation: z
                 .boolean()
                 .optional()
-                .describe('Whether this system has an active compliance violation on record'),
+                .describe('True when SDWIS lists an open violation for this system. Present only on has_violation searches, which return only such systems.'),
             isActive: z
                 .boolean()
                 .optional()
@@ -69,6 +78,12 @@ export const searchWaterSystemsTool = tool('epa_search_water_systems', {
             .optional()
             .describe('Recovery hint when no systems are found. Absent when systems are returned.'),
     }),
+    enrichment: {
+        notice: z
+            .string()
+            .optional()
+            .describe('Present when the has_violation check read only part of what it needed — the first 1,000 open violation records for the state, the first 1,000 systems in the ZIP, or the first 1,000 open violation records for a group of the ZIP’s systems — so violating systems outside that part may be missing from the results.'),
+    },
     errors: [
         {
             reason: 'no_geographic_filter',
@@ -135,7 +150,7 @@ export const searchWaterSystemsTool = tool('epa_search_water_systems', {
             if (s.primarySourceCode)
                 lines.push(`**Primary Source:** ${s.primarySourceCode}`);
             if (s.hasViolation !== undefined)
-                lines.push(`**Active Violation:** ${s.hasViolation ? 'Yes' : 'No'}`);
+                lines.push(`**Open Violation:** ${s.hasViolation ? 'Yes' : 'No'}`);
             if (s.isActive !== undefined)
                 lines.push(`**Active:** ${s.isActive ? 'Yes' : 'No'}`);
         }

package/dist/mcp-server/tools/definitions/search-water-systems.tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"search-water-systems.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-water-systems.tool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"search-water-systems.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-water-systems.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/format-lbs.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Renders a pound quantity for tool text output without rounding away small values.
+ * @module mcp-server/tools/format-lbs
+ */
+/**
+ * Format a quantity in pounds as `"<n> lbs"`, grouped and at full reported precision.
+ *
+ * Default `toLocaleString()` stops at 3 fraction digits, so a TRI release of 0.00062 lbs prints
+ * as 0.001. TRI quantities carry at most 7 significant digits; 12 keeps every one of them, and
+ * matches the 12 significant digits the DMAP service rounds its per-medium sums and gram-to-pound
+ * conversions to, so text and structuredContent show one value.
+ */
+export declare function formatLbs(lbs: number): string;
+//# sourceMappingURL=format-lbs.d.ts.map

package/dist/mcp-server/tools/format-lbs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-lbs.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/format-lbs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C"}

package/dist/mcp-server/tools/format-lbs.js

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Renders a pound quantity for tool text output without rounding away small values.
+ * @module mcp-server/tools/format-lbs
+ */
+/**
+ * Format a quantity in pounds as `"<n> lbs"`, grouped and at full reported precision.
+ *
+ * Default `toLocaleString()` stops at 3 fraction digits, so a TRI release of 0.00062 lbs prints
+ * as 0.001. TRI quantities carry at most 7 significant digits; 12 keeps every one of them, and
+ * matches the 12 significant digits the DMAP service rounds its per-medium sums and gram-to-pound
+ * conversions to, so text and structuredContent show one value.
+ */
+export function formatLbs(lbs) {
+    return `${lbs.toLocaleString(undefined, { maximumSignificantDigits: 12 })} lbs`;
+}
+//# sourceMappingURL=format-lbs.js.map

package/dist/mcp-server/tools/format-lbs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-lbs.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/format-lbs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,OAAO,GAAG,GAAG,CAAC,cAAc,CAAC,SAAS,EAAE,EAAE,wBAAwB,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC;AAClF,CAAC"}

package/dist/mcp-server/tools/format-location.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Renders the address, county, and coordinate lines shared by facility and site tool output.
+ * @module mcp-server/tools/format-location
+ */
+interface LocatedRecord {
+    city?: string | undefined;
+    county?: string | undefined;
+    fipsCode?: string | undefined;
+    latitude?: number | undefined;
+    longitude?: number | undefined;
+    state?: string | undefined;
+    street?: string | undefined;
+    zip?: string | undefined;
+}
+/** Markdown lines for a record's address, county (with FIPS), and coordinates; absent parts are skipped. */
+export declare function formatLocationLines(r: LocatedRecord): string[];
+export {};
+//# sourceMappingURL=format-location.d.ts.map

package/dist/mcp-server/tools/format-location.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-location.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/format-location.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAED,4GAA4G;AAC5G,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,EAAE,CAc9D"}

package/dist/mcp-server/tools/format-location.js

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Renders the address, county, and coordinate lines shared by facility and site tool output.
+ * @module mcp-server/tools/format-location
+ */
+/** Markdown lines for a record's address, county (with FIPS), and coordinates; absent parts are skipped. */
+export function formatLocationLines(r) {
+    const lines = [];
+    const address = [r.street, r.city, r.state, r.zip].filter(Boolean).join(', ');
+    if (address)
+        lines.push(`**Location:** ${address}`);
+    if (r.county)
+        lines.push(`**County:** ${r.county}${r.fipsCode ? ` (FIPS: ${r.fipsCode})` : ''}`);
+    else if (r.fipsCode)
+        lines.push(`**County FIPS:** ${r.fipsCode}`);
+    if (r.latitude !== undefined && r.longitude !== undefined) {
+        lines.push(`**Coordinates:** ${r.latitude}, ${r.longitude}`);
+    }
+    else if (r.latitude !== undefined) {
+        lines.push(`**Latitude:** ${r.latitude}`);
+    }
+    else if (r.longitude !== undefined) {
+        lines.push(`**Longitude:** ${r.longitude}`);
+    }
+    return lines;
+}
+//# sourceMappingURL=format-location.js.map

package/dist/mcp-server/tools/format-location.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-location.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/format-location.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,4GAA4G;AAC5G,MAAM,UAAU,mBAAmB,CAAC,CAAgB;IAClD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9E,IAAI,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,iBAAiB,OAAO,EAAE,CAAC,CAAC;IACpD,IAAI,CAAC,CAAC,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;SAC5F,IAAI,CAAC,CAAC,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;IAClE,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAC1D,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;IAC/D,CAAC;SAAM,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACpC,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC5C,CAAC;SAAM,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACrC,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/mcp-server/tools/format-tri-release.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Renders the unit note and release-quantity lines shared by the TRI tools' text output.
+ * @module mcp-server/tools/format-tri-release
+ */
+interface TriReleaseQuantities {
+    releasesToAirInLbs?: number | undefined;
+    releasesToLandInLbs?: number | undefined;
+    releasesToUndergroundInjectionInLbs?: number | undefined;
+    releasesToWaterInLbs?: number | undefined;
+    reportedUnit?: 'grams' | undefined;
+    totalReleasesInLbs?: number | undefined;
+}
+/** Markdown lines for a TRI record's reported unit and per-medium and one-time quantities; absent fields are skipped. */
+export declare function formatTriReleaseLines(r: TriReleaseQuantities): string[];
+export {};
+//# sourceMappingURL=format-tri-release.d.ts.map

package/dist/mcp-server/tools/format-tri-release.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-tri-release.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/format-tri-release.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,UAAU,oBAAoB;IAC5B,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,mCAAmC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzD,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACnC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,yHAAyH;AACzH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAiBvE"}

package/dist/mcp-server/tools/format-tri-release.js

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Renders the unit note and release-quantity lines shared by the TRI tools' text output.
+ * @module mcp-server/tools/format-tri-release
+ */
+import { formatLbs } from './format-lbs.js';
+/** Markdown lines for a TRI record's reported unit and per-medium and one-time quantities; absent fields are skipped. */
+export function formatTriReleaseLines(r) {
+    const lines = [];
+    if (r.reportedUnit)
+        lines.push(`**Reported Unit:** ${r.reportedUnit} — any quantities shown are converted to pounds (1 lb = 453.59237 g)`);
+    if (r.releasesToAirInLbs !== undefined)
+        lines.push(`**Air Releases:** ${formatLbs(r.releasesToAirInLbs)}`);
+    if (r.releasesToWaterInLbs !== undefined)
+        lines.push(`**Water Releases:** ${formatLbs(r.releasesToWaterInLbs)}`);
+    if (r.releasesToLandInLbs !== undefined)
+        lines.push(`**Land Releases:** ${formatLbs(r.releasesToLandInLbs)}`);
+    if (r.releasesToUndergroundInjectionInLbs !== undefined)
+        lines.push(`**Underground Injection:** ${formatLbs(r.releasesToUndergroundInjectionInLbs)}`);
+    if (r.totalReleasesInLbs !== undefined)
+        lines.push(`**One-Time / Non-Routine Release:** ${formatLbs(r.totalReleasesInLbs)}`);
+    return lines;
+}
+//# sourceMappingURL=format-tri-release.js.map

package/dist/mcp-server/tools/format-tri-release.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-tri-release.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/format-tri-release.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAW7D,yHAAyH;AACzH,MAAM,UAAU,qBAAqB,CAAC,CAAuB;IAC3D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,CAAC,CAAC,YAAY;QAChB,KAAK,CAAC,IAAI,CACR,sBAAsB,CAAC,CAAC,YAAY,sEAAsE,CAC3G,CAAC;IACJ,IAAI,CAAC,CAAC,kBAAkB,KAAK,SAAS;QACpC,KAAK,CAAC,IAAI,CAAC,qBAAqB,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAC;IACrE,IAAI,CAAC,CAAC,oBAAoB,KAAK,SAAS;QACtC,KAAK,CAAC,IAAI,CAAC,uBAAuB,SAAS,CAAC,CAAC,CAAC,oBAAoB,CAAC,EAAE,CAAC,CAAC;IACzE,IAAI,CAAC,CAAC,mBAAmB,KAAK,SAAS;QACrC,KAAK,CAAC,IAAI,CAAC,sBAAsB,SAAS,CAAC,CAAC,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC;IACvE,IAAI,CAAC,CAAC,mCAAmC,KAAK,SAAS;QACrD,KAAK,CAAC,IAAI,CAAC,8BAA8B,SAAS,CAAC,CAAC,CAAC,mCAAmC,CAAC,EAAE,CAAC,CAAC;IAC/F,IAAI,CAAC,CAAC,kBAAkB,KAAK,SAAS;QACpC,KAAK,CAAC,IAAI,CAAC,uCAAuC,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAC;IACvF,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/services/airnow/airnow-service.d.ts

@@ -1,44 +1,25 @@
 /**
- * @fileoverview AirNow API service for real-time and forecast air quality data.
- * Wraps www.airnowapi.org/aq endpoints. Responses cached at ~1 hour TTL per the
- * AirNow API's recommendation to avoid rate-limiting.
+ * @fileoverview AirNow API service for current observations and issued forecasts.
+ * Wraps the 2026 www.airnowapi.org/aq web services `observation/current/ziplatlong/`
+ * and `forecast/current/`. Responses cached at ~1 hour TTL per the AirNow API's
+ * recommendation to avoid rate-limiting.
  * @module services/airnow/airnow-service
  */
 import type { Context } from '@cyanheads/mcp-ts-core';
 import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
 import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
-import type { AirQualityResult } from './types.js';
+import type { AirNowLocation, AirQualityLookup } from './types.js';
 export declare class AirNowService {
     private readonly baseUrl;
     private readonly apiKey;
     constructor(_config: AppConfig, _storage: StorageService);
+    /** Current hourly observations: per pollutant, the closest monitor within AirNow's 50-mile boundary. */
+    getCurrent(location: AirNowLocation, ctx: Context): Promise<AirQualityLookup>;
+    /** Every forecast day the location's reporting area has issued. */
+    getForecast(location: AirNowLocation, ctx: Context): Promise<AirQualityLookup>;
     private buildUrl;
     private cacheKey;
-    private fetchWithCache;
-    /** Get current air quality by ZIP code. */
-    getCurrentByZip(params: {
-        zipCode: string;
-        distanceMiles?: number;
-    }, ctx: Context): Promise<AirQualityResult[]>;
-    /** Get current air quality by lat/lng. */
-    getCurrentByLatLng(params: {
-        latitude: number;
-        longitude: number;
-        distanceMiles?: number;
-    }, ctx: Context): Promise<AirQualityResult[]>;
-    /** Get air quality forecast by ZIP code. */
-    getForecastByZip(params: {
-        zipCode: string;
-        date: string;
-        distanceMiles?: number;
-    }, ctx: Context): Promise<AirQualityResult[]>;
-    /** Get air quality forecast by lat/lng. */
-    getForecastByLatLng(params: {
-        latitude: number;
-        longitude: number;
-        date: string;
-        distanceMiles?: number;
-    }, ctx: Context): Promise<AirQualityResult[]>;
+    private fetchBody;
 }
 export declare function initAirNowService(config: AppConfig, storage: StorageService): void;
 export declare function getAirNowService(): AirNowService;

package/dist/services/airnow/airnow-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"airnow-service.d.ts","sourceRoot":"","sources":["../../../src/services/airnow/airnow-service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAGrE,OAAO,KAAK,EAAE,gBAAgB,EAAmB,MAAM,YAAY,CAAC;AAsCpE,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,YAAY,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAWvD;IAED,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,QAAQ;YAWF,cAAc;IAuC5B,2CAA2C;IACrC,eAAe,CACnB,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,EACD,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAO7B;IAED,0CAA0C;IACpC,kBAAkB,CACtB,MAAM,EAAE;QACN,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,EACD,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAW7B;IAED,4CAA4C;IACtC,gBAAgB,CACpB,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,EACD,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAW7B;IAED,2CAA2C;IACrC,mBAAmB,CACvB,MAAM,EAAE;QACN,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,EACD,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAgB7B;CACF;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAElF;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAKhD"}
+{"version":3,"file":"airnow-service.d.ts","sourceRoot":"","sources":["../../../src/services/airnow/airnow-service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAM/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAGrE,OAAO,KAAK,EACV,cAAc,EAEd,gBAAgB,EAGjB,MAAM,YAAY,CAAC;AA+HpB,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,YAAY,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAWvD;IAED,wGAAwG;IAClG,UAAU,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAKlF;IAED,mEAAmE;IAC7D,WAAW,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAKnF;IAED,OAAO,CAAC,QAAQ;IAUhB,OAAO,CAAC,QAAQ;YAUF,SAAS;CA6DxB;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAElF;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAKhD"}

package/dist/services/airnow/airnow-service.js

@@ -1,43 +1,127 @@
 /**
- * @fileoverview AirNow API service for real-time and forecast air quality data.
- * Wraps www.airnowapi.org/aq endpoints. Responses cached at ~1 hour TTL per the
- * AirNow API's recommendation to avoid rate-limiting.
+ * @fileoverview AirNow API service for current observations and issued forecasts.
+ * Wraps the 2026 www.airnowapi.org/aq web services `observation/current/ziplatlong/`
+ * and `forecast/current/`. Responses cached at ~1 hour TTL per the AirNow API's
+ * recommendation to avoid rate-limiting.
  * @module services/airnow/airnow-service
  */
-import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { serializationError, serviceUnavailable, validationError, } from '@cyanheads/mcp-ts-core/errors';
 import { httpErrorFromResponse, withRetry } from '@cyanheads/mcp-ts-core/utils';
 import { getServerConfig } from '../../config/server-config.js';
 const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
-/** Normalize raw AirNow records (grouped by reporting area) into AirQualityResult[]. */
-function normalizeRecords(records) {
-    // Group by reporting area + date/hour
-    const grouped = new Map();
-    for (const r of records) {
-        const key = `${r.ReportingArea ?? ''}|${r.DateObserved ?? ''}|${r.HourObserved ?? ''}`;
-        let entry = grouped.get(key);
-        if (!entry) {
-            entry = {
-                ...(r.ReportingArea && { reportingArea: r.ReportingArea.trim() }),
-                ...(r.StateCode && { stateCode: r.StateCode }),
-                ...(r.Latitude !== undefined && { latitude: r.Latitude }),
-                ...(r.Longitude !== undefined && { longitude: r.Longitude }),
-                ...(r.DateObserved && { dateObserved: r.DateObserved.trim() }),
-                ...(r.HourObserved !== undefined && { hourObserved: r.HourObserved }),
-                ...(r.LocalTimeZone && { localTimeZone: r.LocalTimeZone }),
+/**
+ * Budget for one AirNow lookup — every attempt and backoff — kept under the 60 s default request
+ * timeout of MCP SDK clients with room for transport.
+ */
+const REQUEST_DEADLINE_MS = 55_000;
+/** The six AirNow AQI descriptors (lowercased) and their category numbers. */
+const AQI_CATEGORY_NUMBERS = new Map([
+    ['good', 1],
+    ['moderate', 2],
+    ['unhealthy for sensitive groups', 3],
+    ['unhealthy', 4],
+    ['very unhealthy', 5],
+    ['hazardous', 6],
+]);
+/** The message(s) of an `{"WebServiceError":[{"Message":…}]}` body; undefined for any other shape. */
+function webServiceErrorMessage(body) {
+    if (typeof body !== 'object' || body === null || !('WebServiceError' in body))
+        return;
+    const entries = body.WebServiceError;
+    if (!Array.isArray(entries))
+        return;
+    const messages = entries.flatMap((entry) => typeof entry?.Message === 'string' && entry.Message.trim() !== '' ? [entry.Message] : []);
+    return messages.length > 0 ? messages.join(' ') : undefined;
+}
+/** Classify a 200 body. Anything but a record array or a WebServiceError message fails loudly. */
+function parseBody(text) {
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch (cause) {
+        throw serializationError('AirNow returned a response that is not JSON.', undefined, { cause });
+    }
+    if (Array.isArray(body))
+        return { rows: body };
+    const noDataMessage = webServiceErrorMessage(body);
+    if (noDataMessage !== undefined)
+        return { noDataMessage };
+    throw serializationError('AirNow returned an unrecognized response: expected an array of records or a WebServiceError message.');
+}
+/** An AQI value, or undefined when upstream sent none (forecasts use -1 for category-only). */
+function validAqi(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+/** Group observation records by reporting area and observed hour; one reading per pollutant. */
+function normalizeObservations(rows) {
+    const areas = new Map();
+    for (const r of rows) {
+        const aqi = validAqi(r.nowcastAQI);
+        if (!r.parameterName || (aqi === undefined && !r.aqiCategoryName))
+            continue;
+        const key = [r.reportingAreaName, r.dateObserved, r.hourObserved, r.localTimeZone].join('|');
+        let area = areas.get(key);
+        if (!area) {
+            area = {
+                ...(r.reportingAreaName && { reportingArea: r.reportingAreaName }),
+                ...(r.dateObserved && { dateObserved: r.dateObserved }),
+                ...(r.hourObserved && { hourObserved: r.hourObserved }),
+                ...(r.localTimeZone && { localTimeZone: r.localTimeZone }),
                 readings: [],
             };
-            grouped.set(key, entry);
+            areas.set(key, area);
         }
-        if (r.ParameterName && r.AQI !== undefined) {
-            entry.readings.push({
-                parameterName: r.ParameterName,
-                aqi: r.AQI,
-                ...(r.Category?.Number !== undefined && { categoryNumber: r.Category.Number }),
-                ...(r.Category?.Name && { categoryName: r.Category.Name }),
-            });
+        const categoryNumber = r.aqiCategoryName
+            ? AQI_CATEGORY_NUMBERS.get(r.aqiCategoryName.trim().toLowerCase())
+            : undefined;
+        area.readings.push({
+            parameterName: r.parameterName,
+            ...(aqi !== undefined && { aqi }),
+            ...(r.aqiCategoryName && { categoryName: r.aqiCategoryName }),
+            ...(categoryNumber !== undefined && { categoryNumber }),
+            ...(r.siteName && { siteName: r.siteName }),
+            ...(r.siteID && { siteID: r.siteID }),
+            ...(r.reportingAgency && { reportingAgency: r.reportingAgency }),
+        });
+    }
+    return [...areas.values()];
+}
+/** Group forecast records by reporting area; one reading per pollutant per valid date. */
+function normalizeForecasts(rows) {
+    const areas = new Map();
+    for (const r of rows) {
+        const aqi = validAqi(r.aqi);
+        if (!r.parameterName ||
+            (aqi === undefined && !r.categoryName && r.categoryNumber === undefined)) {
+            continue;
         }
+        const key = r.reportingAreaCode ?? r.reportingArea ?? '';
+        let area = areas.get(key);
+        if (!area) {
+            area = {
+                ...(r.reportingArea && { reportingArea: r.reportingArea }),
+                ...(r.reportingAreaCode && { reportingAreaCode: r.reportingAreaCode }),
+                ...(r.stateCode && { stateCode: r.stateCode }),
+                readings: [],
+            };
+            areas.set(key, area);
+        }
+        // AirNow repeats the area's discussion on every row; keep it once, verbatim.
+        if (!area.discussion && r.discussion)
+            area.discussion = r.discussion;
+        area.readings.push({
+            parameterName: r.parameterName,
+            ...(aqi !== undefined && { aqi }),
+            ...(r.categoryNumber !== undefined && { categoryNumber: r.categoryNumber }),
+            ...(r.categoryName && { categoryName: r.categoryName }),
+            ...(r.dateIssue && { dateIssue: r.dateIssue }),
+            ...(r.dateValid && { dateValid: r.dateValid }),
+            ...(r.forecastAgency && { forecastAgency: r.forecastAgency }),
+            ...(typeof r.actionDay === 'boolean' && { actionDay: r.actionDay }),
+        });
     }
-    return Array.from(grouped.values());
+    return [...areas.values()];
 }
 export class AirNowService {
     baseUrl;
@@ -52,20 +136,31 @@ export class AirNowService {
         this.baseUrl = serverConfig.airNowBaseUrl;
         this.apiKey = serverConfig.airNowApiKey;
     }
+    /** Current hourly observations: per pollutant, the closest monitor within AirNow's 50-mile boundary. */
+    async getCurrent(location, ctx) {
+        const body = await this.fetchBody('observation', location, ctx);
+        return 'noDataMessage' in body
+            ? { areas: [], noDataMessage: body.noDataMessage }
+            : { areas: normalizeObservations(body.rows) };
+    }
+    /** Every forecast day the location's reporting area has issued. */
+    async getForecast(location, ctx) {
+        const body = await this.fetchBody('forecast', location, ctx);
+        return 'noDataMessage' in body
+            ? { areas: [], noDataMessage: body.noDataMessage }
+            : { areas: normalizeForecasts(body.rows) };
+    }
     buildUrl(path, params) {
         const url = new URL(`${this.baseUrl}/${path}`);
         url.searchParams.set('format', 'application/json');
         url.searchParams.set('API_KEY', this.apiKey);
         for (const [key, val] of Object.entries(params)) {
-            if (val !== undefined && val !== '') {
-                url.searchParams.set(key, String(val));
-            }
+            url.searchParams.set(key, String(val));
         }
         return url.toString();
     }
     cacheKey(kind, params) {
         const stable = Object.entries(params)
-            .filter(([, v]) => v !== undefined)
             .sort(([a], [b]) => a.localeCompare(b))
             .map(([k, v]) => `${k}-${String(v).replace(/[^a-zA-Z0-9_.\-/]/g, '_')}`)
             .join('_');
@@ -73,15 +168,33 @@ export class AirNowService {
         const safeKind = kind.replace(/:/g, '/');
         return `airnow/${safeKind}/${stable}`;
     }
-    async fetchWithCache(url, cacheKey, ctx) {
-        // Try cache first
+    async fetchBody(service, location, ctx) {
+        const params = location.kind === 'zip'
+            ? { zipCode: location.zipCode }
+            : { latitude: location.latitude, longitude: location.longitude };
+        const cacheKey = this.cacheKey(`${service}:${location.kind}`, params);
         const cached = await ctx.state.get(cacheKey);
         if (cached && cached.expiresAt > Date.now()) {
             ctx.log.debug('AirNow cache hit', { cacheKey });
-            return cached.data;
+            return cached.body;
         }
-        const data = await withRetry(async () => {
-            const response = await fetch(url, { signal: ctx.signal });
+        const path = service === 'observation' ? 'observation/current/ziplatlong/' : 'forecast/current/';
+        const url = this.buildUrl(path, params);
+        ctx.log.debug('AirNow request', { service, ...params });
+        const body = await withRetry(async ({ signal }) => {
+            const response = await fetch(url, { signal });
+            // A ZIP is the only caller-supplied input on a ZIP request, so a 400 rejects it.
+            if (response.status === 400 && location.kind === 'zip') {
+                const upstream = await response.text();
+                let detail;
+                try {
+                    detail = webServiceErrorMessage(JSON.parse(upstream));
+                }
+                catch {
+                    // Non-JSON 400 body: report the status alone.
+                }
+                throw validationError(`AirNow rejected zip_code "${location.zipCode}": ${detail ?? 'HTTP 400'}.`, { reason: 'invalid_zip_code', zipCode: location.zipCode });
+            }
             if (!response.ok) {
                 throw await httpErrorFromResponse(response, { service: 'AirNow' });
             }
@@ -89,69 +202,15 @@ export class AirNowService {
             if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
                 throw serviceUnavailable('AirNow API returned HTML instead of JSON — likely rate-limited.');
             }
-            const parsed = JSON.parse(text);
-            return Array.isArray(parsed) ? parsed : [];
+            return parseBody(text);
         }, {
-            operation: 'AirNowService.fetch',
+            operation: 'AirNow request',
             baseDelayMs: 2000,
             signal: ctx.signal,
+            deadlineMs: REQUEST_DEADLINE_MS,
         });
-        // Store in cache
-        await ctx.state.set(cacheKey, { data, expiresAt: Date.now() + CACHE_TTL_MS });
-        return data;
-    }
-    /** Get current air quality by ZIP code. */
-    async getCurrentByZip(params, ctx) {
-        const qparams = { zipCode: params.zipCode, distance: params.distanceMiles ?? 25 };
-        const url = this.buildUrl('observation/zipCode/current/', qparams);
-        const ck = this.cacheKey('current:zip', qparams);
-        ctx.log.debug('AirNow current by ZIP', { zipCode: params.zipCode });
-        const records = await this.fetchWithCache(url, ck, ctx);
-        return normalizeRecords(records);
-    }
-    /** Get current air quality by lat/lng. */
-    async getCurrentByLatLng(params, ctx) {
-        const qparams = {
-            latitude: params.latitude,
-            longitude: params.longitude,
-            distance: params.distanceMiles ?? 25,
-        };
-        const url = this.buildUrl('observation/latLong/current/', qparams);
-        const ck = this.cacheKey('current:latlng', qparams);
-        ctx.log.debug('AirNow current by lat/lng', { lat: params.latitude, lng: params.longitude });
-        const records = await this.fetchWithCache(url, ck, ctx);
-        return normalizeRecords(records);
-    }
-    /** Get air quality forecast by ZIP code. */
-    async getForecastByZip(params, ctx) {
-        const qparams = {
-            zipCode: params.zipCode,
-            date: params.date,
-            distance: params.distanceMiles ?? 25,
-        };
-        const url = this.buildUrl('forecast/zipCode/', qparams);
-        const ck = this.cacheKey('forecast:zip', qparams);
-        ctx.log.debug('AirNow forecast by ZIP', { zipCode: params.zipCode, date: params.date });
-        const records = await this.fetchWithCache(url, ck, ctx);
-        return normalizeRecords(records);
-    }
-    /** Get air quality forecast by lat/lng. */
-    async getForecastByLatLng(params, ctx) {
-        const qparams = {
-            latitude: params.latitude,
-            longitude: params.longitude,
-            date: params.date,
-            distance: params.distanceMiles ?? 25,
-        };
-        const url = this.buildUrl('forecast/latLong/', qparams);
-        const ck = this.cacheKey('forecast:latlng', qparams);
-        ctx.log.debug('AirNow forecast by lat/lng', {
-            lat: params.latitude,
-            lng: params.longitude,
-            date: params.date,
-        });
-        const records = await this.fetchWithCache(url, ck, ctx);
-        return normalizeRecords(records);
+        await ctx.state.set(cacheKey, { body, expiresAt: Date.now() + CACHE_TTL_MS });
+        return body;
     }
 }
 // --- Init/accessor pattern ---