TrailSmith — 天候対応型カルパティア山脈旅程エージェント（MCP課題）

リポジトリ: https://github.com/mashta-lilia/trailsmith-mcp-agent （完全なコミット履歴あり。このアーカイブは、あるコミット時点で追跡されたファイルのエクスポートです）

チョルノホラ山脈における複数日にわたるハイキング旅程を検証・リスク評価・再計画する、ドメイン特化型データエージェントです。2つのMCP接続を使用します:

• 既存サーバー（パートA）: OpenWeather MCP — 集落ごとの5日間ライブ予報。

• カスタムサーバー（パートB）: trailsmith（このリポジトリ、trailsmith_mcp/）— ローカルの厳選トレイルデータセットに対する4つのドメインツール。

エージェント（Claude Agent SDK）は旅程を検証し、日ごとに日次評価サブエージェントを1つずつ並列で生成し（予報 → 決定的パース → リスクスコア）、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-ignored、.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 [city]（既存サーバー）。

エージェントは自身の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/には、明確にラベル付けされた合成入力（本物の記録の1つの条件行を変更したもの）が、そのブランチを実行するために保持されています。その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のユニットテストが、検証ルール、リスクヒューリスティック、グラフ検索、ロジスティクス、予報テキストパーサー（不正な入力を含む）、およびレビュー中に見つかったすべてのコントラクトと正確性のバグの回帰テストをカバーしています。

ドキュメント

**ドキュメントインデックス**から始めてください。

スクリプト