.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/national-parks-mcp-server</h1> <p><b>Plan US National Park Service trips — find parks, check alerts and closures, find campgrounds, browse things to do and events via the NPS Data API. STDIO or Streamable HTTP.</b> <div>6 Tools</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

<div align="center">

Public Hosted Server: https://national-parks.caseyjhand.com/mcp

</div>

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")
• 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 over the returned page (narrows what was fetched; does not search all ~470 sites)
• Pagination via limit (1–50, default 10) and start offset
• 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)
• 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)
• Sorted most-recent-first; format() orders Danger / Park Closure ahead of the rest
• categoryBreakdown enrichment counts returned alerts per category so severity is legible without scanning each one
• An empty result is explicitly framed as good news (the park reports nothing closed or hazardous), not an 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:

• One service wrapping the NPS Data API (developer.nps.gov/api/v1, X-Api-Key auth) across six trip-planning endpoints
• Aggressive normalization of NPS's inconsistent payloads — numeric and boolean fields returned as strings, nested values (campsites.totalSites), array-typed amenity fields, and the distinct /events envelope with lowercased field names — coerced to clean domain types before they reach handlers
• nps_get_park batches up to ten park codes into a single upstream request
• Light retry on transient upstream failures (5xx / network); a missing or invalid key fails loud and names NPS_API_KEY

Agent-friendly output:

• Result-set context on every response — totalCount, truncation (shown / cap), applied-filter echo, and empty-result notices reach both the structured and text surfaces
• The parkCode-first workflow is encoded in every tool description; nps_get_park returns missingCodes so a wrong code self-corrects
• Uncertainty preserved, never fabricated — every derived field is nullable and a missing upstream value yields null, not a guess; coordinates are never invented for downstream weather lookups

Getting started

Public Hosted Instance

A public instance is available at https://national-parks.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP, with this client config:

{
  "mcpServers": {
    "national-parks-mcp-server": {
      "type": "streamable-http",
      "url": "https://national-parks.caseyjhand.com/mcp"
    }
  }
}

Self-hosted

Add the following to your MCP client configuration file. A free NPS Data API key is required — instant signup here.

{
  "mcpServers": {
    "national-parks-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/national-parks-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NPS_API_KEY": "your-api-key"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "national-parks-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/national-parks-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NPS_API_KEY": "your-api-key"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "national-parks-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "NPS_API_KEY=your-api-key",
        "ghcr.io/cyanheads/national-parks-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 NPS_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3 or higher (or Node.js v24+).
• A free NPS Data API key — instant signup. The server fails to start without it.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/national-parks-mcp-server.git

1. Navigate into the directory:

cd national-parks-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env
# edit .env and set NPS_API_KEY

Configuration

All configuration is validated at startup via Zod schemas. Key environment variables:

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild

  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t national-parks-mcp-server .
docker run --rm -e NPS_API_KEY=your-key -p 3010:3010 national-parks-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/national-parks-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See AGENTS.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 request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools in the createApp() arrays
• Wrap the external API: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Data & attribution

Data is retrieved from the NPS Data API operated by the U.S. National Park Service. Content produced by NPS employees in their official capacity is a U.S. Government work in the public domain (17 U.S.C. §§ 101 and 105). No claim to original U.S. Government works.

Not all content returned by the API is government-authored. Some images and materials carry third-party copyright or other restrictions — check individual item rights before reuse.

The NPS Arrowhead symbol is a restricted mark protected under 18 U.S.C. § 701. It must not be reproduced or reused without written permission from the NPS Director.