Skip to main content
Glama

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を編集します:

変数

必要な用途

ANTHROPIC_API_KEY

エージェント(Claude Agent SDK)。claude /loginを実行済みなら任意。

OWM_API_KEY

ライブOpenWeather呼び出し。新しいキーは有効化に最大~2時間かかります。

OPENWEATHER_MCP_BIN

任意の上書き; デフォルトはbin\mcp-openweather.exe。

REPLAY

1でライブAPIの代わりに記録済みフィクスチャを提供。

FIXTURE_SET

任意のリプレイディレクトリ名; デフォルトはopenweather。

シークレットは.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を手動で起動すると、プロセス分離と独立起動可能性を示します。

デモ入力

ファイル

目的

demo/itinerary_clean.json

3日間の谷間/混合トラバース — クリーンパス

demo/itinerary_storm.json

2日目が露出したTurkul尾根を横断します。再計画は嵐の天気下でのみ発動します — FIXTURE_SET=scenario_stormで実行してください(下記参照)

demo/itinerary_invalid.json

不明なセグメントID — 構造化エラーデモ

demo/itinerary_5day.json

変更された有効な入力: 5日間、高フィットネス

demo/itinerary_lowfitness.json

変更された有効な入力: 低フィットネス → 1日目に1つのソフトDAILY_ASCENT_EXCEEDED違反

**ライブデモの前に、**を実行してください — 日付を予報ウィンドウ内に移動し、本物のフィクスチャを再記録し、新しい日付に対して嵐シナリオをワンステップで再構築します。

デモの日付はライブの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のユニットテストが、検証ルール、リスクヒューリスティック、グラフ検索、ロジスティクス、予報テキストパーサー(不正な入力を含む)、およびレビュー中に見つかったすべてのコントラクトと正確性のバグの回帰テストをカバーしています。

ドキュメント

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

ドキュメント

回答内容

クイックスタート

これをどうやって動かすの?

アーキテクチャ

どう組み立てられ、各結果はどこに行くの?

ツールコントラクト

各ツールは正確に何を受け入れ、何を返すの?

設計根拠

なぜこの方法なのか、制限は何か?

トラブルシューティング

なぜドキュメント通りに動作しないのか?

デモスクリプト

どのようにデモするの?

データセットの出所

トレイルデータはどこから来たの?

スクリプト

スクリプト

目的

scripts/refresh_demo.py

今日のデモを準備: デモ日付を予報ウィンドウに移動し、本物のフィクスチャを再記録し、日付固定の嵐シナリオを再構築し、デモコマンドを出力します

scripts/verify.py

システム全体のワンコマンド証明: 両方のMCP接続、プロセス分離、エラーコントラクト、障害劣化、データセット再現性、テスト

scripts/walkthrough.py

ドメインワークフロー全体を決定的に実行、LLMや認証情報は不要

scripts/smoke_custom_server.py

カスタムサーバーを別プロセスで起動し、そのツールを一覧表示して呼び出します

scripts/smoke_weather_server.py

既存のOpenWeather MCPサーバーを呼び出します(キーが必要)

scripts/fetch_fixtures.py

オフラインリプレイ用に本物のAPI応答を記録します

scripts/replay_weather_server.py

同じweatherコントラクトで記録済みフィクスチャを提供します

scripts/build_dataset.py

トレイルデータセットを決定的に再生成します

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers