TrailSmith — 天气感知的喀尔巴阡山脉行程代理（MCP 作业）

仓库： https://github.com/mashta-lilia/trailsmith-mcp-agent （完整提交历史；本归档为某一提交时点跟踪文件的导出）

一个领域特定的数据代理，用于验证、风险评估和重新规划乔尔诺霍拉山脉的多日徒步行程。它使用两个 MCP 连接：

• 现有服务器（A 部分）： OpenWeather MCP — 按聚落实时 5 天预报。

• 自定义服务器（B 部分）： trailsmith（本仓库，trailsmith_mcp/）— 基于本地精选步道数据集的四个领域工具。

该代理（Claude Agent SDK）验证行程，为每天并行生成一个日评估子代理（预报 → 确定性解析 → 风险评分），为 no_go 天生成重新规划子代理，合并并重新验证，最终生成带有从原始预报文本到决策的可见价值追踪的最终计划。

一条命令即可试用（无需 API 密钥）

python -m venv .venv
.\.venv\Scripts\pip install -r requirements.txt
.\.venv\Scripts\python scripts\walkthrough.py demo\itinerary_storm.json --fixtures scenario_storm

该命令针对记录的预报运行整个规划工作流 — 验证、为每天评分、重新规划危险日、估算后勤 — 无需 LLM 和凭据：

[2] day 2 2026-08-21  NESAMOVYTE -> BYSTRETS  (10.2 km, 500 m)
    forecast: 2026-08-21 conditions='Thunderstorm thunderstorm with heavy rain' ...
    risk: 100 no_go
      +70  thunderstorm_on_exposed_ridge: Thunderstorm forecast on an exposed ridge.
      +35  wet_exposed_ridge: 25.0 mm precipitation on an exposed ridge at 2036 m: ...
[3] day 2 is no_go - replanning
    chose ['CH-022', 'CH-014'] (9.3 km) -> 60 caution [relaxation: none]

包含实时天气和代理的完整演练：docs/quickstart.md。

Related MCP server: GemmaJnana

先决条件

• Python 3.12+（已在 3.13 上测试）

• Go 1.21+（仅用于构建 OpenWeather MCP 二进制文件）

• OpenWeatherMap API 密钥（免费层）和 Anthropic API 密钥

安装

PowerShell，从仓库根目录：

python -m venv .venv
.\.venv\Scripts\pip install -r requirements.txt
go install github.com/mschneider82/mcp-openweather@latest
New-Item -ItemType Directory -Force bin
Copy-Item "$env:USERPROFILE\go\bin\mcp-openweather.exe" bin\
Copy-Item .env.example .env

然后编辑 .env：

机密信息仅存在于 .env 中（git 已忽略，包括任何 .env.* 变体）。未提交任何敏感内容。

独立启动命令

• 自定义 MCP 服务器（独立进程）： .\.venv\Scripts\python -m trailsmith_mcp

• 代理： .\.venv\Scripts\python -m agent.runner demo\itinerary_clean.json

• 冒烟测试：.\.venv\Scripts\python scripts\smoke_custom_server.py（通过 stdio 发现并调用自定义服务器），.\.venv\Scripts\python scripts\smoke_weather_server.py [城市]（现有服务器）。

代理自行启动 MCP 连接；手动启动 trailsmith_mcp 演示了进程分离和独立可启动性。

演示输入

在实时演示之前，运行 — 它将日期移入预报窗口，重新记录真实测试数据，并一步重建针对新日期的风暴场景。

演示日期必须落在实时 5 天预报窗口内。 它们设置为 2026-08-20 及之后；在实时演示之前，将每个 date 提前并重新运行 scripts/fetch_fixtures.py。在窗口之外，解析器会正确抛出 NO_FORECAST_FOR_DATE，当天降级为 weather_known=false / caution — 这是一个合法路径，但不是你想要展示为干净运行的路径。

测试数据和离线重放

• 记录真实响应：.\.venv\Scripts\python scripts\fetch_fixtures.py 将逐字工具文本保存到 fixtures/openweather/。它还会记录无效城市响应 — 该服务器将其作为成功的全零主体返回而非错误，因此保存为普通 .txt。没有 .error.txt 测试数据，因为上游服务器从未产生过。

• 离线重放：设置 REPLAY=1 并正常运行代理。重放服务器（scripts/replay_weather_server.py）暴露相同的 weather 契约并逐字提供记录的文本 — 代理的解析和错误处理不变地运行；没有预解析。

  $env:REPLAY=1
  .\.venv\Scripts\python -m agent.runner demo\itinerary_clean.json

• 风暴场景。 no_go 风险需要雷暴或恶劣条件，而喀尔巴阡山脉的预报通常缺乏这些 — 在平静的日子里，代理正确报告 ok/caution 且从不重新规划，因此无法按需演示重新规划分支。fixtures/scenario_storm/ 包含一个明确标记的合成输入（在真实记录中更改了一行条件）用于演练该分支；请参阅其 README，并在演示时披露。选择它：

  $env:REPLAY=1; $env:FIXTURE_SET="scenario_storm"
  .\.venv\Scripts\python -m agent.runner demo\itinerary_storm.json

速率限制

OpenWeatherMap 免费层允许 60 次调用/分钟。实际限制我们调用量的是：

• validate_itinerary 拒绝超过 7 天 的行程（Itinerary.days 有 max_length=7），因此最多生成 7 个日评估器。

• 每个日评估器上限为 maxTurns=6，因此失败后不会在天气 API 上循环。

• 因此最坏情况远低于每分钟限制。并行批次的 宽度 由 Claude Code CLI 的 Task 调度器决定，而非此代码 — 我们限制调用总数，而非并发数。

成本护栏（agent/orchestrator.py）：主循环上 max_budget_usd=1.50 和 max_turns=30，外加每个子代理的 maxTurns。这些是硬性 SDK 限制，而非提示指令；agent/runner.py 打印运行的轮数和美元成本，并标记因达到上限而停止的运行。

验证整个系统

.\.venv\Scripts\python scripts\verify.py

运行 12 项检查 — 两个 MCP 连接及其工具发现、进程分离、每个连接上的成功调用、结构化错误与空成功、不可用预报上的保守降级、字节一致的数据集重新生成，以及测试套件。无需 Anthropic 凭据。

测试

.\.venv\Scripts\python -m pytest tests -q

45 个单元测试涵盖验证规则、风险启发式、图搜索、物流、预报文本解析器（包括格式错误的输入），以及审查期间发现的每个契约和正确性错误的回归测试。

文档

从 文档索引 开始。

脚本