nws-weather-mcp-server: Instructions file for Codex

Agent Protocol

Server: nws-weather-mcp-server Version: 0.11.1 Framework: @cyanheads/mcp-ts-core ^0.13.15 Engines: Bun ≥1.4.0, Node ≥24.0.0 MCP SDK: @modelcontextprotocol/server ^2.3.1 Zod: ^4.6.7

Read the framework docs first: node_modules/@cyanheads/mcp-ts-core/CLAUDE.md contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.

Domain

Full design in docs/design.md. Key constraints:

• API base: https://api.weather.gov — no auth, but requires a User-Agent header (403 without it).
• Coordinate-centric: Most workflows start with GET /points/{lat},{lon}, which returns a grid cell with URLs for forecast, hourly forecast, observation stations, and zones. This is the routing layer — follow the returned URLs rather than constructing grid endpoints manually.
• Grid caching: /points responses are highly cacheable (grid cells don't change). Cached in-process via a Map with 1h TTL — grid cells are geography, not tenant data.
• Units are metric: Temperature in Celsius, wind in km/h, pressure in Pa, precipitation in mm. Convert to readable format in format() (show both F/C, mph, inHg/hPa, in/mm).
• No geocoding: API is coordinates-only. Tools accept lat/lon directly.
• Alert quirks: /alerts/active has no limit param (returns 400) and no upstream cursor. Filter by area/severity, then window the fetched array locally. /alerts/active/count rejects every query parameter with a 400, so nws_get_alert_counts takes no filters.
• Transient 500s: Grid forecast endpoints occasionally fail. Retry with backoff.
• Hourly = 156 periods: Handler windows returned periods to 48 so structuredContent and content[] share the same bounded set; pre-page total + truncation notice surfaced via enrichment.
• Paging is local windowing, with one upstream exception. nws_get_forecast, nws_find_stations, and nws_search_alerts each fetch their whole collection, then window it locally. Each takes an opaque cursor input and surfaces nextCursor as enrichment, omitted on the last page per the MCP spec, so the Zod field is .optional() and never .nullable(). nws_find_stations windows with paginateArray from @cyanheads/mcp-ts-core/utils (the generic pagination utility — not the tenant-scoped, signed encodeCursor/decodeCursor pair in the storage layer). paginateArray re-mints { offset, limit } only, so the two tools whose query a call can change mint their own token with the generic encodeCursor/decodeCursor pair it builds on: nws_search_alerts carries the normalized filters (area, point, zone, region_type, region, event, severity, urgency, certainty, status), and nws_get_forecast carries its mode (daily or hourly), each beside offset and limit. Both decode the token before any NWS request. On a continued page the carried query governs and the matching inputs are ignored, as limit is; a token without it ({ offset, limit }, the earlier shape) still decodes and takes its query from the inputs. A token that does not decode, carries a non-integer offset or limit, or carries filters that fail the input checks (alerts) or a non-boolean mode (forecast) fails as -32602 InvalidParams (invalid_cursor); nws_find_stations gets the same from decodeCursor. Leave it; do not convert it to a declared errors[] reason. Nothing caches the fetched collection (only /points grid resolution, 1h), so pages are contiguous within one response and not across separate calls: never document or promise a cross-call no-gap/no-overlap guarantee, least of all for alerts. The exception is nws_get_observation_history, which pages upstream, because a station's observation history has no bounded collection to fetch (NWS keeps ~7 days, and a busy station reports every 5 minutes). It mints its own keyset cursor with encodeCursor/decodeCursor from @cyanheads/mcp-ts-core/utils — the generic pair paginateArray builds on, not the storage layer's — carrying the first page's start and applied limit with the oldest returned timestamp as the next end; NWS's own pagination.next never reaches input or output. Each request asks NWS for one record past the page, so nextCursor appears only when that extra record comes back (a window holding exactly limit observations ends with no cursor), no totalCount is reported (NWS gives none for a window), and a cursor this tool did not mint fails as -32602 InvalidParams (invalid_cursor) before any request. On nws_find_stations, nws_search_alerts, and nws_get_observation_history, a first-page limit past the page cap is served as the cap rather than rejected and disclosed through requestedLimit/effectiveLimit enrichment (clampPageLimit in src/mcp-server/tools/page-limit.ts); the schema ceiling is .max(10000).