nation park MCP

户外和公园智能MCP服务器

A. 模型上下文协议（MCP） 通过键入工具公开结构化户外智能的服务器。 服务器聚合来自多个外部提供商（公园、天气、空气质量）的数据，验证输入和输出，并返回适用于自动和人工评估的确定性JSON响应。

服务器充当语言模型和外部环境数据提供者之间的受控执行层，执行严格的合同、可预测的行为和操作保护措施，如重试、速率限制和错误规范化。

目录

• 范围
• 数据提供程序

- 天气 - 空气质量

• 可用的MCP工具

- 停车和定位工具 - 安全和上下文工具 - 环境工具

• 安装

- 先决条件 - 诗歌 - pip/venv

• 配置

- API密钥

• 开发和测试

- 运行测试 - 代码质量 - 预提交钩子

• 错误模型
• 项目结构
• 扩展

- 添加提供者 - 添加工具

• 贡献
• 致谢

______________________________________________________________________

范围

此MCP服务器为以下各项提供统一接口：

• 国家公园和位置元数据
• 安全和操作警报
• 环境条件（天气、空气质量）
• 从多个数据源得出的上下文摘要

所有功能都通过具有严格输入/输出模式的MCP工具公开。

______________________________________________________________________

数据提供程序

• 国家公园管理局（NPS）

美国国家公园管理局的官方国家数据源，提供权威的公园数据，包括公园、警报、游客中心、露营地和活动。 通过配置 NPS_API_KEY.

天气

• 开放天气 （默认值；不需要API密钥）
• 开放天气 （可选；基于API密钥）

供应商选择策略： 如果 OPENWEATHER_API_KEY 如果已配置，服务器将首先尝试OpenWeather，并在提供程序失败时回退到Open Meteo。

空气质量

• IQAir/AirVisual API

提供空气质量指数和污染物数据。需要 AIRVISUAL_API_KEY. 如果未配置密钥，空气质量请求将返回结构化配置错误。

______________________________________________________________________

可用的MCP工具

停车和定位工具

• #### findParks

按州、关键字和活动搜索公园。

• #### getParkDetails

检索完整的公园配置文件。

• #### getVisitorCenters

检索公园的游客中心数据。

• #### getCampgrounds

检索公园的露营地数据。

• #### getEvents

检索与公园相关的事件。

安全和上下文工具

• #### getAlerts

检索活动警报和警告。

• #### getParkContext

返回一个包含公园元数据、警报和安全信息的压缩上下文对象。

环境工具

• #### getWeather

检索实时天气状况。

• #### getAirQuality

检索空气质量指数和污染物数据。

所有工具：

• 使用Pydantic模型验证输入
• 仅返回结构化JSON
• 一致机器可读格式的表面误差

______________________________________________________________________

安装

先决条件

• python 3.10+
• 诗歌（推荐）或pip

诗歌

git clone https://github.com/ester-bloch/Outdoor-Parks-Intelligence-MCP.git
cd Outdoor-Parks-Intelligence-MCP
poetry install

pip/venv

git clone https://github.com/ester-bloch/Outdoor-Parks-Intelligence-MCP.git
cd Outdoor-Parks-Intelligence-MCP
python -m venv .venv
pip install -e .

______________________________________________________________________

配置

API密钥

1. 从以下项生成API密钥：

• NPS_API_KEY （必填） — 国家公园管理局
• OPENWEATHER_API_KEY （可选） — 开放天气
• AIRVISUAL_API_KEY （可选） — IQAir/空气视觉

1. 复制示例环境文件：

   cp .env.example .env

1. 编辑 .env 并设置配置值：

   # Required
   NPS_API_KEY=your_nps_api_key_here

   # Optional (enable air quality)
   AIRVISUAL_API_KEY=your_airvisual_api_key_here

   # Optional (prefer OpenWeather; otherwise Open-Meteo is used)
   OPENWEATHER_API_KEY=your_openweather_api_key_here

______________________________________________________________________

使用Poetry运行服务器

poetry run python -m src.main

使用venv运行

python -m src.main

服务器运行超时 标准根据MCP惯例。

______________________________________________________________________

开发和测试

运行测试

poetry run pytest
poetry run pytest --cov=src --cov-report=html
poetry run pytest tests/unit/
poetry run pytest tests/integration/
poetry run pytest tests/property/

代码质量

poetry run black src tests
poetry run isort src tests
poetry run flake8 src tests
poetry run mypy src

预提交钩子

pre-commit run --all-files
pre-commit run black
pre-commit run mypy

______________________________________________________________________

错误模型

所有错误都以结构化JSON对象的形式返回，并分类为：

• 输入验证错误
• 配置缺失或无效
• 上游提供商HTTP错误
• 网络和超时故障

不会产生自由文本或隐式错误响应。

______________________________________________________________________

项目结构

developer 2/
├── docs/
│   └── claude_desktop_config.json
├── scripts/
│   └── demo.py
├── src/
│   ├── api/
│   │   ├── __init__.py
│   │   ├── air_quality.py
│   │   ├── client.py
│   │   ├── rate_limit.py
│   │   ├── retry.py
│   │   └── weather.py
│   ├── handlers/
│   │   ├── __init__.py
│   │   ├── find_parks.py
│   │   ├── get_air_quality.py
│   │   ├── get_alerts.py
│   │   ├── get_campgrounds.py
│   │   ├── get_events.py
│   │   ├── get_park_context.py
│   │   ├── get_park_details.py
│   │   ├── get_visitor_centers.py
│   │   └── get_weather.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── errors.py
│   │   ├── external.py
│   │   ├── requests.py
│   │   └── responses.py
│   ├── utils/
│   │   ├── __init__.py
│   │   ├── error_handler.py
│   │   ├── formatters.py
│   │   ├── geo.py
│   │   └── logging.py
│   ├── __init__.py
│   ├── config.py
│   ├── constants.py
│   ├── main.py
│   └── server.py
├── tests/
│   ├── integration/
│   │   ---
│   ├── property/
│   │   ---
│   ├── unit/
│   │   ---
│   ├── __init__.py
│   └── conftest.py
├── .env.example
├── .flake8
├── .gitignore
├── .pre-commit-config.yaml
├── poetry.lock
├── pyproject.toml
├── requirements-dev.txt
└── requirements.txt

主要惯例：

• src/api/ 包含提供程序客户端和弹性原语（重试/速率限制）。
• src/handlers/ 包含MCP工具实现（每个工具一个文件）。
• src/models/ 定义请求/响应模式和规范化错误模型。
• tests/ 按测试意图（单元/集成/属性）划分。
• 生成的伪影（例如。， __pycache__/, *.pyc)是开发的副产品，不应该进行版本控制。

______________________________________________________________________

扩展

添加提供者

1. 在中实现客户端 src/api/
2. 在中注册配置密钥 .env.example
3. 通过处理程序集成，无需跨提供者耦合

添加工具

1. 实现逻辑 src/handlers/
2. 在中定义架构 src/models/
3. 在中注册该工具 server.py

______________________________________________________________________

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 运行测试并确保代码质量
5. 提交拉取请求

______________________________________________________________________

致谢

• 建于 FastMCP
• 数据由以下机构提供：

- 国家公园管理局API - 开放天气 - 开放天气 - IQAir/空气视觉