@cyanheads/nws-weather-mcp-server 0.3.1

package/README.md

@@ -0,0 +1,249 @@
+<div align="center">
+  <h1>@cyanheads/nws-weather-mcp-server</h1>
+  <p><b>Real-time US weather data via the National Weather Service API. Forecasts, alerts, and observations with zero auth.</b></p>
+  <p><b>5 Tools · 1 Resource</b></p>
+</div>
+
+<div align="center">
+
+[![npm](https://img.shields.io/npm/v/@cyanheads/nws-weather-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/nws-weather-mcp-server) [![Version](https://img.shields.io/badge/Version-0.3.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) 
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.2+-blueviolet.svg?style=flat-square)](https://bun.sh/)
+
+</div>
+
+---
+
+## Tools
+
+Five tools for real-time US weather data:
+
+| Tool | Description |
+|:----------|:------------|
+| `nws_get_forecast` | 7-day or hourly forecast for coordinates. Resolves NWS grid internally. |
+| `nws_search_alerts` | Active weather alerts filtered by area, point, zone, event, severity. |
+| `nws_get_observations` | Current conditions by coordinates (nearest station) or station ID. |
+| `nws_find_stations` | Nearby observation stations sorted by distance with bearing. |
+| `nws_list_alert_types` | All valid alert event type names for filter discovery. |
+
+### `nws_get_forecast`
+
+Get the weather forecast for a US location.
+
+- Default returns named 12-hour periods (14 total, ~7 days)
+- Hourly mode returns up to 156 one-hour periods with dewpoint and humidity
+- Coordinates resolve to NWS grid internally via `/points` endpoint
+
+---
+
+### `nws_search_alerts`
+
+Search active weather alerts with flexible filtering.
+
+- Filter by area (state/territory/marine codes), point (lat,lon), zone, event type, severity, urgency, certainty
+- National search when no filters provided
+- Results capped at 25 with truncation notice and guidance to narrow filters
+- Validates area codes and point format before API call
+
+---
+
+### `nws_get_observations`
+
+Current measured conditions from a weather station.
+
+- Look up by coordinates (finds nearest station) or station ID directly
+- Dual-unit display: F/C, mph/km/h, inHg/hPa, mi/km
+- Warns when most measurements are unavailable from a station
+
+---
+
+### `nws_find_stations`
+
+Discover nearby observation stations.
+
+- Sorted by haversine distance from query point
+- Returns distance (km) and compass bearing
+- Includes zone codes, elevation, time zone
+- Useful for finding station IDs for `nws_get_observations`
+
+---
+
+### `nws_list_alert_types`
+
+List all valid NWS alert event type names.
+
+- Returns the full set of event types the NWS API recognizes (e.g., "Tornado Warning", "Heat Advisory")
+- Use to discover valid values for the `event` filter in `nws_search_alerts`
+
+## Resources
+
+| URI Pattern | Description |
+|:------------|:------------|
+| `nws://alert-types` | Static list of all valid NWS alert event type names. |
+
+## Features
+
+Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):
+
+- Declarative tool definitions — single file per tool, framework handles registration and validation
+- Unified error handling across all tools
+- Pluggable auth (`none`, `jwt`, `oauth`)
+- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
+- Structured logging with optional OpenTelemetry tracing
+- Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase
+
+NWS-specific:
+
+- Zero-auth access to the NWS API — no API keys required
+- Automatic coordinate-to-grid resolution with caching (1h TTL)
+- Retry with backoff for transient NWS API failures
+- Dual-unit display for observations (F/C, mph/km/h, inHg/hPa, mi/km)
+- Continental US, Alaska, Hawaii, and US territories coverage
+
+## Getting started
+
+Add the following to your MCP client configuration file.
+
+```json
+{
+  "mcpServers": {
+    "nws-weather": {
+      "type": "stdio",
+      "command": "bunx",
+      "args": ["@cyanheads/nws-weather-mcp-server@latest"],
+      "env": {
+        "MCP_TRANSPORT_TYPE": "stdio",
+        "MCP_LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+Or with npx (no Bun required):
+
+```json
+{
+  "mcpServers": {
+    "nws-weather": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@cyanheads/nws-weather-mcp-server@latest"],
+      "env": {
+        "MCP_TRANSPORT_TYPE": "stdio",
+        "MCP_LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+Or with Docker:
+
+```json
+{
+  "mcpServers": {
+    "nws-weather": {
+      "type": "stdio",
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/nws-weather-mcp-server:latest"]
+    }
+  }
+}
+```
+
+For Streamable HTTP, set the transport and start the server:
+
+```sh
+MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
+# Server listens at http://localhost:3010/mcp
+```
+
+### Prerequisites
+
+- [Node.js v22+](https://nodejs.org/) or [Bun v1.2+](https://bun.sh/)
+
+### Installation
+
+1. **Clone the repository:**
+
+```sh
+git clone https://github.com/cyanheads/nws-weather-mcp-server.git
+```
+
+2. **Navigate into the directory:**
+
+```sh
+cd nws-weather-mcp-server
+```
+
+3. **Install dependencies:**
+
+```sh
+bun install
+```
+
+## Configuration
+
+| Variable | Description | Default |
+|:---------|:------------|:--------|
+| `NWS_USER_AGENT` | User-Agent for NWS API requests. The API requires this header. | `(nws-weather-mcp-server, ...)` |
+| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
+| `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |
+| `MCP_HTTP_HOST` | Hostname for HTTP server. | `127.0.0.1` |
+| `MCP_LOG_LEVEL` | Log level: `debug`, `info`, `notice`, `warning`, `error`. | `info` |
+
+See [`.env.example`](.env.example) for the full list including auth, storage, and OpenTelemetry options.
+
+## Running the server
+
+### Local development
+
+- **Build and run the production version:**
+
+  ```sh
+  # One-time build
+  bun run rebuild
+
+  # Run the built server
+  bun run start:http
+  # or
+  bun run start:stdio
+  ```
+
+- **Run checks and tests:**
+
+  ```sh
+  bun run devcheck     # Lints, formats, type-checks
+  bun run test         # Runs test suite
+  ```
+
+## Project structure
+
+| Directory | Purpose |
+|:----------|:--------|
+| `src/mcp-server/tools/definitions/` | Tool definitions (`*.tool.ts`). |
+| `src/mcp-server/resources/definitions/` | Resource definitions (`*.resource.ts`). |
+| `src/services/nws/` | NWS API client and response types. |
+| `src/config/` | Environment variable parsing and validation with Zod. |
+
+## Development guide
+
+See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
+
+- Handlers throw, framework catches — no `try/catch` in tool logic
+- Use `ctx.log` for domain-specific logging, `ctx.state` for storage
+- Add new tools/resources to the barrel exports and the `createApp()` arrays in `src/index.ts`
+
+## Contributing
+
+Issues and pull requests are welcome. Run checks before submitting:
+
+```sh
+bun run devcheck
+bun run test
+```
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE) for details.

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

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Server-specific configuration for nws-weather-mcp-server.
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+declare const ServerConfigSchema: z.ZodObject<{
+    userAgent: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type ServerConfig = z.infer<typeof ServerConfigSchema>;
+export declare function getServerConfig(): ServerConfig;
+export {};
+//# sourceMappingURL=server-config.d.ts.map

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

@@ -0,0 +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;AAE3C,QAAA,MAAM,kBAAkB;;iBAKtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAK9C"}

package/dist/config/server-config.js

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Server-specific configuration for nws-weather-mcp-server.
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+const ServerConfigSchema = z.object({
+    userAgent: z
+        .string()
+        .default('(nws-weather-mcp-server, github.com/cyanheads/nws-weather-mcp-server)')
+        .describe('User-Agent header for NWS API requests. Required by the API — 403 without it.'),
+});
+let _config;
+export function getServerConfig() {
+    _config ??= ServerConfigSchema.parse({
+        userAgent: process.env.NWS_USER_AGENT,
+    });
+    return _config;
+}
+//# sourceMappingURL=server-config.js.map

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

@@ -0,0 +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;AAE3C,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,OAAO,CAAC,uEAAuE,CAAC;SAChF,QAAQ,CAAC,+EAA+E,CAAC;CAC7F,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,kBAAkB,CAAC,KAAK,CAAC;QACnC,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc;KACtC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview nws-weather-mcp-server MCP server entry point.
+ * @module index
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG"}

package/dist/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview nws-weather-mcp-server MCP server entry point.
+ * @module index
+ */
+import { createApp } from '@cyanheads/mcp-ts-core';
+import { alertTypesResource } from './mcp-server/resources/definitions/index.js';
+import { findStationsTool, getForecastTool, getObservationsTool, listAlertTypesTool, searchAlertsTool, } from './mcp-server/tools/definitions/index.js';
+import { initNwsService } from './services/nws/nws-service.js';
+await createApp({
+    tools: [
+        getForecastTool,
+        searchAlertsTool,
+        getObservationsTool,
+        findStationsTool,
+        listAlertTypesTool,
+    ],
+    resources: [alertTypesResource],
+    setup() {
+        initNwsService();
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,6CAA6C,CAAC;AACjF,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,SAAS,CAAC;IACd,KAAK,EAAE;QACL,eAAe;QACf,gBAAgB;QAChB,mBAAmB;QACnB,gBAAgB;QAChB,kBAAkB;KACnB;IACD,SAAS,EAAE,CAAC,kBAAkB,CAAC;IAC/B,KAAK;QACH,cAAc,EAAE,CAAC;IACnB,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/resources/definitions/alert-types.resource.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Resource: nws://alert-types — static list of valid NWS alert event type names.
+ * @module mcp-server/resources/definitions/alert-types
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const alertTypesResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{}, z.core.$strip>, undefined>;
+//# sourceMappingURL=alert-types.resource.d.ts.map

package/dist/mcp-server/resources/definitions/alert-types.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert-types.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/alert-types.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAGrD,eAAO,MAAM,kBAAkB,gGAsB7B,CAAC"}

package/dist/mcp-server/resources/definitions/alert-types.resource.js

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Resource: nws://alert-types — static list of valid NWS alert event type names.
+ * @module mcp-server/resources/definitions/alert-types
+ */
+import { resource, z } from '@cyanheads/mcp-ts-core';
+import { getNwsService } from '../../../services/nws/nws-service.js';
+export const alertTypesResource = resource('nws://alert-types', {
+    name: 'NWS Alert Event Types',
+    description: 'Static list of all valid NWS alert event type names. Useful reference when constructing event filters for nws_search_alerts.',
+    mimeType: 'application/json',
+    params: z.object({}),
+    async handler(_params, ctx) {
+        const types = await getNwsService().listAlertTypes(ctx);
+        return { count: types.length, eventTypes: [...types].sort() };
+    },
+    list: async () => ({
+        resources: [
+            {
+                uri: 'nws://alert-types',
+                name: 'NWS Alert Event Types',
+                description: 'All valid alert event type names for filtering.',
+                mimeType: 'application/json',
+            },
+        ],
+    }),
+});
+//# sourceMappingURL=alert-types.resource.js.map

package/dist/mcp-server/resources/definitions/alert-types.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert-types.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/alert-types.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAE9D,MAAM,CAAC,MAAM,kBAAkB,GAAG,QAAQ,CAAC,mBAAmB,EAAE;IAC9D,IAAI,EAAE,uBAAuB;IAC7B,WAAW,EACT,8HAA8H;IAChI,QAAQ,EAAE,kBAAkB;IAC5B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;IAEpB,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG;QACxB,MAAM,KAAK,GAAG,MAAM,aAAa,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;QACxD,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;IAChE,CAAC;IAED,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACjB,SAAS,EAAE;YACT;gBACE,GAAG,EAAE,mBAAmB;gBACxB,IAAI,EAAE,uBAAuB;gBAC7B,WAAW,EAAE,iDAAiD;gBAC9D,QAAQ,EAAE,kBAAkB;aAC7B;SACF;KACF,CAAC;CACH,CAAC,CAAC"}

package/dist/mcp-server/resources/definitions/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Barrel export for all resource definitions.
+ * @module mcp-server/resources/definitions
+ */
+export { alertTypesResource } from './alert-types.resource.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp-server/resources/definitions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/mcp-server/resources/definitions/index.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Barrel export for all resource definitions.
+ * @module mcp-server/resources/definitions
+ */
+export { alertTypesResource } from './alert-types.resource.js';
+//# sourceMappingURL=index.js.map

package/dist/mcp-server/resources/definitions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/mcp-server/tools/definitions/find-stations.tool.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Tool: nws_find_stations — finds nearby weather observation stations.
+ * @module mcp-server/tools/definitions/find-stations
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const findStationsTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    latitude: z.ZodNumber;
+    longitude: z.ZodNumber;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    stations: z.ZodArray<z.ZodObject<{
+        stationId: z.ZodString;
+        name: z.ZodString;
+        distance: z.ZodNumber;
+        bearing: z.ZodString;
+        elevation: z.ZodNullable<z.ZodNumber>;
+        timeZone: z.ZodString;
+        county: z.ZodString;
+        forecastZone: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+//# sourceMappingURL=find-stations.tool.d.ts.map

package/dist/mcp-server/tools/definitions/find-stations.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-stations.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/find-stations.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAGjD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;kBAuE3B,CAAC"}

package/dist/mcp-server/tools/definitions/find-stations.tool.js

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Tool: nws_find_stations — finds nearby weather observation stations.
+ * @module mcp-server/tools/definitions/find-stations
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { getNwsService } from '../../../services/nws/nws-service.js';
+export const findStationsTool = tool('nws_find_stations', {
+    description: 'Find weather observation stations near a location. Returns stations sorted by proximity with distance and bearing. Use to discover station IDs for nws_get_observations.',
+    annotations: { readOnlyHint: true },
+    input: z.object({
+        latitude: z.number().min(-90).max(90).describe('Center latitude for proximity search.'),
+        longitude: z.number().min(-180).max(180).describe('Center longitude for proximity search.'),
+        limit: z.number().int().min(1).max(50).default(10).describe('Max stations to return (1-50).'),
+    }),
+    output: z.object({
+        stations: z
+            .array(z.object({
+            stationId: z.string().describe('Station identifier (e.g., "KSEA")'),
+            name: z.string().describe('Station name'),
+            distance: z.number().describe('Distance from query point in km'),
+            bearing: z.string().describe('Compass bearing from query point (e.g., "NW")'),
+            elevation: z.number().nullable().describe('Elevation in meters'),
+            timeZone: z.string().describe('IANA time zone'),
+            county: z.string().describe('County zone code (e.g., "WAC033")'),
+            forecastZone: z.string().describe('Forecast zone code (e.g., "WAZ315")'),
+        }))
+            .describe('Nearby stations sorted by distance'),
+    }),
+    async handler(input, ctx) {
+        const result = await getNwsService().findStations(input.latitude, input.longitude, input.limit, ctx);
+        return {
+            stations: result.stations.map((s) => ({
+                stationId: s.stationId,
+                name: s.name,
+                distance: s.distance,
+                bearing: s.bearing,
+                elevation: s.elevation.value != null ? Math.round(s.elevation.value) : null,
+                timeZone: s.timeZone,
+                county: s.county,
+                forecastZone: s.forecastZone,
+            })),
+        };
+    },
+    format: (result) => {
+        if (result.stations.length === 0) {
+            return [{ type: 'text', text: 'No stations found near this location.' }];
+        }
+        const lines = [
+            `## ${result.stations.length} Nearby Station${result.stations.length > 1 ? 's' : ''}\n`,
+        ];
+        lines.push('| Station | Name | Distance | Bearing | Elevation | Time Zone |');
+        lines.push('|:--------|:-----|:---------|:--------|:----------|:----------|');
+        for (const s of result.stations) {
+            const elev = s.elevation != null ? `${Math.round(s.elevation)}m` : '—';
+            lines.push(`| ${s.stationId} | ${s.name} | ${s.distance} km | ${s.bearing} | ${elev} | ${s.timeZone} |`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=find-stations.tool.js.map

package/dist/mcp-server/tools/definitions/find-stations.tool.js.map

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

package/dist/mcp-server/tools/definitions/get-forecast.tool.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Tool: nws_get_forecast — retrieves weather forecast for US coordinates.
+ * @module mcp-server/tools/definitions/get-forecast
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const getForecastTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    latitude: z.ZodNumber;
+    longitude: z.ZodNumber;
+    hourly: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    location: z.ZodObject<{
+        city: z.ZodString;
+        state: z.ZodString;
+        office: z.ZodString;
+        timeZone: z.ZodString;
+    }, z.core.$strip>;
+    generatedAt: z.ZodString;
+    periods: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        startTime: z.ZodString;
+        endTime: z.ZodString;
+        temperature: z.ZodNumber;
+        temperatureUnit: z.ZodString;
+        windSpeed: z.ZodString;
+        windDirection: z.ZodString;
+        shortForecast: z.ZodString;
+        detailedForecast: z.ZodString;
+        precipChance: z.ZodNullable<z.ZodNumber>;
+        dewpoint: z.ZodNullable<z.ZodNumber>;
+        relativeHumidity: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+//# sourceMappingURL=get-forecast.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-forecast.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-forecast.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-forecast.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAgBjD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;kBAkI1B,CAAC"}

package/dist/mcp-server/tools/definitions/get-forecast.tool.js

@@ -0,0 +1,125 @@
+/**
+ * @fileoverview Tool: nws_get_forecast — retrieves weather forecast for US coordinates.
+ * @module mcp-server/tools/definitions/get-forecast
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { getNwsService } from '../../../services/nws/nws-service.js';
+import { cToF, formatTimestamp, fToC } from '../format-utils.js';
+/** Derive a period label from startTime when name is empty (hourly periods). */
+function periodLabel(name, startTime) {
+    if (name)
+        return name;
+    const d = new Date(startTime);
+    if (Number.isNaN(d.getTime()))
+        return startTime;
+    return d.toLocaleString('en-US', {
+        weekday: 'short',
+        hour: 'numeric',
+        minute: '2-digit',
+    });
+}
+export const getForecastTool = tool('nws_get_forecast', {
+    description: 'Get the weather forecast for a US location. Returns either named 12-hour periods (default) or hourly breakdowns. Internally resolves coordinates to the NWS grid.',
+    annotations: { readOnlyHint: true },
+    input: z.object({
+        latitude: z
+            .number()
+            .min(-90)
+            .max(90)
+            .describe('Latitude in decimal degrees (e.g., 47.6062). Truncated to 4 decimal places.'),
+        longitude: z
+            .number()
+            .min(-180)
+            .max(180)
+            .describe('Longitude in decimal degrees (e.g., -122.3321). Truncated to 4 decimal places.'),
+        hourly: z
+            .boolean()
+            .default(false)
+            .describe('If true, returns hourly forecast (~156 periods) instead of 12-hour named periods (14 periods). Hourly includes dewpoint and relative humidity.'),
+    }),
+    output: z.object({
+        location: z
+            .object({
+            city: z.string().describe('City name'),
+            state: z.string().describe('State name'),
+            office: z.string().describe('NWS Weather Forecast Office code'),
+            timeZone: z.string().describe('IANA time zone'),
+        })
+            .describe('Resolved location metadata'),
+        generatedAt: z.string().describe('When the forecast was generated (ISO 8601)'),
+        periods: z
+            .array(z.object({
+            name: z.string().describe('Period name (e.g., "Today", "Tonight") or hour label'),
+            startTime: z.string().describe('Period start (ISO 8601)'),
+            endTime: z.string().describe('Period end (ISO 8601)'),
+            temperature: z.number().describe('Temperature value'),
+            temperatureUnit: z.string().describe('Temperature unit (F or C)'),
+            windSpeed: z.string().describe('Wind speed (e.g., "10 mph")'),
+            windDirection: z.string().describe('Wind direction (e.g., "NW")'),
+            shortForecast: z.string().describe('Brief forecast (e.g., "Mostly Sunny")'),
+            detailedForecast: z.string().describe('Full narrative forecast'),
+            precipChance: z.number().nullable().describe('Probability of precipitation (%)'),
+            dewpoint: z.number().nullable().describe('Dewpoint in Celsius (hourly only)'),
+            relativeHumidity: z.number().nullable().describe('Relative humidity % (hourly only)'),
+        }))
+            .describe('Forecast periods'),
+    }),
+    async handler(input, ctx) {
+        const result = await getNwsService().getForecast(input.latitude, input.longitude, input.hourly, ctx);
+        return {
+            location: result.location,
+            generatedAt: result.forecast.generatedAt,
+            periods: result.forecast.periods.map((p) => ({
+                name: p.name,
+                startTime: p.startTime,
+                endTime: p.endTime,
+                temperature: p.temperature,
+                temperatureUnit: p.temperatureUnit,
+                windSpeed: p.windSpeed,
+                windDirection: p.windDirection,
+                shortForecast: p.shortForecast,
+                detailedForecast: p.detailedForecast,
+                precipChance: p.probabilityOfPrecipitation.value,
+                dewpoint: p.dewpoint.value != null ? Math.round(p.dewpoint.value * 10) / 10 : null,
+                relativeHumidity: p.relativeHumidity.value != null ? Math.round(p.relativeHumidity.value * 10) / 10 : null,
+            })),
+        };
+    },
+    format: (result) => {
+        const loc = result.location;
+        const lines = [
+            `## Forecast for ${loc.city}, ${loc.state}`,
+            `**Office:** ${loc.office} | **Time Zone:** ${loc.timeZone} | **Generated:** ${formatTimestamp(result.generatedAt)}`,
+            '',
+        ];
+        if (result.periods.length === 0) {
+            lines.push('No forecast periods available for this location.');
+            return [{ type: 'text', text: lines.join('\n') }];
+        }
+        const periods = result.periods.slice(0, 48);
+        for (const p of periods) {
+            const precip = p.precipChance != null ? ` | **Precip:** ${p.precipChance}%` : '';
+            const humidity = p.relativeHumidity != null ? ` | **Humidity:** ${p.relativeHumidity}%` : '';
+            const dew = p.dewpoint != null
+                ? ` | **Dewpoint:** ${cToF(p.dewpoint)}°F (${Math.round(p.dewpoint)}°C)`
+                : '';
+            lines.push(`### ${periodLabel(p.name, p.startTime)}`);
+            const tempDual = p.temperatureUnit === 'F'
+                ? `${p.temperature}°F (${fToC(p.temperature)}°C)`
+                : `${cToF(p.temperature)}°F (${p.temperature}°C)`;
+            lines.push(`**${tempDual}** | **Wind:** ${p.windSpeed} ${p.windDirection}${precip}${humidity}${dew}`);
+            if (p.detailedForecast) {
+                lines.push(p.detailedForecast);
+            }
+            else {
+                lines.push(p.shortForecast);
+            }
+            lines.push('');
+        }
+        if (result.periods.length > 48) {
+            lines.push(`_...and ${result.periods.length - 48} more periods (${result.periods.length} total)._`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-forecast.tool.js.map