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)

• Ключ API OpenWeatherMap (бесплатный тариф) и ключ API Anthropic

Установка

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 [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/ содержит явно помеченный синтетический вход (одна строка условий изменена в иначе подлинной записи) для отработки этой ветки; см. его 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 после сбоя.

• Худший случай, таким образом, значительно ниже лимита в минуту. Ширина параллельного пакета определяется планировщиком задач CLI Claude Code, а не этим кодом — мы ограничиваем общее количество вызовов, а не их параллельность.

Ограничения стоимости (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 модульных тестов покрывают правила валидации, эвристики риска, поиск по графу, логистику, парсер текста прогноза (включая некорректный ввод) и регрессионные тесты для каждого контракта и ошибки корректности, найденных при ревью.

Документация

Начните с индекса документации.

Скрипты