national-parks-mcp-server

---

概述

规划国家公园管理局行程：查找公园、查看警报和关闭信息，并浏览露营地、活动和事件。涵盖国家公园、纪念地、历史遗址和海岸，不包括州立公园、林务局或土地管理局（BLM）管辖的土地。

工具

工具	描述
nps_find_parks	根据地点名称、美国州名或自由文本查询查找公园 — 必须首先调用。返回每个公园的 parkCode 和行程规划摘要。
nps_get_park	一次批量调用获取最多十个公园的详细信息：简介、活动、费用与通行证、开放时间、联系方式、路线、天气概况和图片。
nps_get_alerts	获取公园或州的当前警报 — 关闭、危险、注意事项和信息 — 优先显示类别和时效信息。
nps_find_campgrounds	查找公园或州内的露营地：设施、可预订与先到先得营位数量、预订信息、无障碍信息和费用。
nps_get_activities	精选游玩项目和景点：标题、时长、地点、无障碍信息，以及费用／宠物／预订标记。
nps_find_events	查找日期范围内安排的事件：日期／时间、地点、类别、费用和注册链接。

能力参考

nps_find_parks _工具

• 自由文本 query、两字母 stateCode（或以逗号分隔的列表，例如 "WY,MT,ID"），以及可选的 activity 筛选条件；limit 为 1–50（默认 10），并可使用 start 偏移量
• 每个公园包含其 parkCode，以及指定类别、州、描述、坐标、主要活动、最低门票费和 NPS 页面；完全匹配的 parkCode 或名称排名靠前，totalCount 统计所有匹配项

---

nps_get_park _工具

• 每次调用最多可查询 10 个 parkCode；可选的 fields 选择器（activities、topics、fees、hours、contacts、directions、images）可将载荷精简至所需部分
• 始终返回名称、指定类别、州、描述、坐标、天气概况和 NPS 页面；还会返回按类别划分的费用和通行证、按区域和季节划分的开放时间、联系方式，以及最多 5 张图片（若该公园有更多图片，则会显示 imagesTruncated）
• 与任何地点都不匹配的代码会列入 missingCodes；只有在没有任何代码匹配时，调用才会失败（no_parks_found）

---

nps_get_alerts _工具

• 可按 parkCode、stateCode、自由文本 query 和 category（Danger、Caution、Information、Park Closure）筛选；limit 为 1–50（默认 20），并可使用 start 偏移量
• 按最新优先排序；每条警报都包含类别、反映时效性的 lastIndexedDate 和详情；categoryBreakdown 按严重程度统计返回的警报数量
• 通知会说明该地点一切正常（没有警报），并将其与筛选条件无匹配项以及页码超出范围的情况区分开来

---

nps_find_campgrounds _工具

• 可按 parkCode、stateCode 或自由文本 query 筛选；limit 为 1–50（默认 15），并可使用 start 偏移量
• 每个营地包含以下设施（饮用水、淋浴、污水倾倒站、厕所、垃圾收集、房车通道），其状态为有、无或未知；还包含可预订、先到先得和营位总数；预订指南和预订 URL；最低费用、无障碍信息、坐标和 NPS 页面

---

nps_get_activities _工具

• 必须提供单个 parkCode 或单个 stateCode，并可选择提供 query；limit 为 1–50（默认 15），并可使用 start 偏移量
• 每项活动包含标题、简短描述、所需时间、地点、坐标、无障碍信息、季节、是否需要预订和是否允许携带宠物的标记、费用说明及 NPS 页面

---

nps_find_events _工具

• 在 dateStart / dateEnd 日期范围（YYYY-MM-DD）内按 parkCode、stateCode 或 query 筛选；使用 pageNumber 和 pageSize（1–50，默认 15）分页，而非使用偏移量
• 每项活动包含标题、日期范围、范围内的 occurrenceDates（isRecurring 表示系列活动）、时间段、地点、类别、费用，以及注册和信息 URL
• NPS 在结果旁报告的错误会并入通知，而不会导致调用失败

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供结构化日志记录和可选的 OpenTelemetry 跟踪。

NPS 特有功能：

• 一个服务通过六个行程规划端点封装 NPS Data API（developer.nps.gov/api/v1，使用 X-Api-Key 身份验证）
• 对 NPS 不一致的负载进行强力规范化——将以字符串形式返回的数值和布尔字段、嵌套值（campsites.totalSites）、数组类型的设施字段，以及具有不同 /events 信封和小写字段名的数据，统一转换为清晰的领域类型，再传递给处理程序
• nps_get_park 可将最多十个公园代码合并到单个上游请求中
• 对上游暂时性故障（5xx / 网络）进行轻量重试；缺少或无效的密钥会明确报错，并指出 NPS_API_KEY
• nps_find_parks / nps_get_park 返回的坐标可供天气服务（nws-weather、open-meteo）用于天气预报

便于 Agent 使用的输出：

• 每个响应都包含结果集上下文——totalCount、截断信息（truncated / shown / cap）、已应用筛选条件的回显，以及无结果提示，并同时呈现在结构化输出和文本输出中
• 许多公园没有露营地、精选活动或事件；无结果时会提示其他查找途径，而不会报错
• 每个工具的描述都采用以 parkCode 为先的工作流；nps_get_park 会返回 missingCodes，帮助自动纠正错误代码
• 保留不确定性，不捏造信息——缺失的坐标、路线、费用和设施值会返回 null，而不是猜测；绝不会为下游天气查询虚构坐标

开始使用

公共托管实例

可使用公共实例：https://national-parks.caseyjhand.com/mcp，无需安装。该实例提供 Streamable HTTP；不同客户端的配置格式各不相同。

对于 Claude Code：

claude mcp add --transport http national-parks-mcp-server https://national-parks.caseyjhand.com/mcp

对于 Cline（cline_mcp_settings.json）：

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

对于 Cursor（mcp.json）：

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

Claude Desktop 可在 Settings → Connectors 下添加远程服务。

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。需要免费的 NPS Data API 密钥——立即注册。

{
  "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"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "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"
      }
    }
  }
}

也可以使用 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"
      ]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

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

前置条件

• Bun v1.4 或更高版本（或 Node.js v24+）。
• 免费的 NPS Data API 密钥——立即注册。没有密钥，服务将无法启动。

安装

1. 克隆代码库：

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

2. 进入目录：

cd national-parks-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

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

配置

所有配置都会在启动时通过 Zod schema 验证。主要环境变量：

变量	描述	默认值
NPS_API_KEY	必需。 NPS Data API 密钥，通过 X-Api-Key 请求头发送。未设置时，服务将无法启动。	—
NPS_BASE_URL	NPS Data API 基础 URL 覆盖值（用于测试 / 代理）。	https://developer.nps.gov/api/v1
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_HTTP_ENDPOINT_PATH	MCP 服务挂载的路径。	/mcp
MCP_SESSION_MODE	会话处理方式：auto、stateful 或 stateless。schema 默认值 auto 会解析为 stateful；此服务会显式设置为 stateless。无论采用哪种模式，MCP 2026-07-28 均为无会话模式。	stateless
MCP_AUTH_MODE	认证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败工具调用的参数和结果，按键名对内容进行脱敏，并将大小限制为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认值为 16384）。自由格式值中的机密不会被脱敏。	false
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry instrumentation（跨度、指标、完成日志）。	false

完整的可选覆盖项列表请参见 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  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

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/national-parks-mcp-server。默认会安装 OpenTelemetry 对等依赖项；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册六个工具并初始化 NPS 服务。
src/config	使用 Zod 解析并验证服务专属环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/services/nps	NPS Data API 服务——HTTP 客户端、重试边界、错误封装检测以及所有上游数据规范化处理。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参见 AGENTS.md / CLAUDE.md。简要说明：

• 处理器抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求级日志记录，使用 ctx.state 进行租户级存储
• 在 createApp() 数组中注册新工具
• 封装外部 API：验证原始数据 → 规范化为领域类型 → 返回输出 schema；绝不伪造缺失字段

数据与署名

数据取自美国国家公园管理局运营的 NPS Data API。NPS 员工履行公务时创作的内容属于美国政府作品，处于公有领域（17 U.S.C. §§ 101 and 105）。不对美国政府原创作品主张权利。

API 返回的内容并非全部由政府创作。部分图像和材料受第三方版权或其他限制保护——重复使用前请核查各条目的权利信息。

NPS Arrowhead 标志是受 18 U.S.C. § 701 保护的限制性标志。未经 NPS 局长书面许可，不得复制或重复使用。

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参见 LICENSE。