Tools

Six tools shaped around the trip-planning workflow — resolve a park, then key the detail tools on its code:

Coverage is US National Park Service sites only — national parks, monuments, historic sites, seashores — not state parks and not Forest Service or BLM land.

The parkCode spine

parkCode (e.g. yose, grca, zion) is the join key for the whole API. The workflow is two steps:

1. nps_find_parks resolves a name / state / query → parkCode(s) plus a summary.
2. nps_get_park, nps_get_alerts, nps_find_campgrounds, nps_get_activities, nps_find_events key on that parkCode.

nps_get_alerts, nps_find_campgrounds, and nps_find_events also accept a stateCode for statewide queries without a code (e.g. "is anything closed in Montana's parks?"). The coordinates returned by nps_find_parks / nps_get_park feed weather servers (nws-weather, open-meteo) for a forecast.

nps_find_parks

Resolve a place name, US state, or free-text query into NPS parks — the entry point.

• Free-text search across park names and descriptions (e.g. "yosemite", "civil war", "redwood"); results are re-ranked locally so an exact parkCode or name match leads, since NPS returns matches in alphabetical-by-code order with no relevance ranking
• Filter by two-letter stateCode or a comma-separated list (e.g. "CA", "WY,MT,ID")
• Optional activity filter — case-insensitive substring match applied locally (the API has no activity param) across every site matching query/stateCode, then paginated
• Pagination via limit (1–50, default 10) and start offset; totalCount counts the whole matched set, so truncation guidance names the next start
• Summary carries parkCode, designation, states, description, coordinates, headline activities, lowest entrance fee, and the NPS page
• Enrichment reports totalCount, applied-filter echo, and broadening guidance when nothing matched

nps_get_park

Full trip-planning detail for one or more parks by parkCode.

• Batch up to 10 codes in a single upstream call
• Always-present core: name, designation, states, description, coordinates, weather overview, NPS page
• Optional fields selector (activities, topics, fees, hours, contacts, directions, images) trims the payload to the sections you need
• Entrance fees and passes broken out by category; operating hours by area/season with per-weekday values; phone and email contacts; representative images (capped at 5, with imagesTruncated disclosing when the park has more upstream)
• Unresolved codes surface as missingCodes enrichment with a correction hint; only a fully-empty result is an error

nps_get_alerts

Current alerts for a park or a whole state, with category and recency leading.

• Filter by parkCode, stateCode, or free-text query; optional category (Danger, Caution, Information, Park Closure) applied locally (the API has no category param) across every matching alert, then paginated
• Pagination via limit (1–50, default 20) and start offset; truncation guidance names the next start
• Sorted most-recent-first, identically on both client surfaces (structuredContent and content[])
• categoryBreakdown enrichment counts returned alerts per category — severity-ordered — so severity is legible without scanning each one
• An empty result is explicitly framed in the notice — good news (the park reports nothing closed or hazardous) when nothing matched, or a paging artifact when start ran past the end — never a bare error
• lastIndexedDate is the recency signal — a stale date may mean the condition has changed

nps_find_campgrounds

Campgrounds at a park or across a state, flattened to what a camper filters on.

• Filter by parkCode, stateCode, or free-text query; limit (1–50, default 15) and start pagination
• Amenity booleans: potable water, showers, RV dump station, toilets, trash collection, RV access — normalized from NPS's mixed array/string amenity fields
• Reservable vs. first-come-first-served site counts, total sites, reservation guidance and booking URL (often recreation.gov)
• Lowest fee, accessibility summary, coordinates, and the campground's NPS page
• Some parks list lodging or backcountry permits instead of NPS-managed campgrounds; an empty result is not an error

nps_get_activities

Curated things to do and points of interest, backed by the NPS /thingstodo list (distinct from a park's raw activity tags).

• Accepts a single 4-letter parkCode or a single two-letter stateCode — at least one is required
• Free-text query; limit (1–50, default 15) and start pagination
• Per activity: title, short description, time commitment, location, coordinates, accessibility, season, and the NPS page
• Reservation-required and pets-permitted booleans; fee description (absence does not guarantee free)
• Not every park has a curated list; an empty result is not an error

nps_find_events

Scheduled events at a park within a date range — ranger programs, festivals, tours, interpretive events.

• Filter by parkCode, stateCode, or free-text query; bound the window with dateStart / dateEnd (YYYY-MM-DD)
• Page-based pagination (pageNumber / pageSize), not offset — the /events endpoint differs from the rest of the API
• Per event: title, date range, time slots, location, category, fee info, and registration / info URLs (HTML stripped to plain text)
• The events feed is sparser and less consistent than alerts or campgrounds; many parks list few or no events
• A non-empty upstream errors[] array folds into the result notice as a warning rather than failing the request

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, 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 — same codebase runs locally or on Cloudflare Workers

NPS-specific: