TrailSmith — 날씨 인지 카르파티아 일정 에이전트 (MCP 과제)

저장소: https://github.com/mashta-lilia/trailsmith-mcp-agent (전체 커밋 기록 포함; 이 아카이브는 한 커밋에서 추적된 파일들의 내보내기입니다)

Chornohora 산맥의 다일 하이킹 일정을 검증·위험 평가·재계획하는 도메인 특화 데이터 에이전트입니다. 두 개의 MCP 연결을 사용합니다:

• 기존 서버(파트 A): OpenWeather MCP — 정착지별 실시간 5일 예보.

• 사용자 지정 서버(파트 B): trailsmith(이 저장소, trailsmith_mcp/) — 로컬 선별 트레일 데이터셋을 위한 4가지 도메인 도구.

에이전트(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/에 그대로 저장합니다. 또한 잘못된 도시 응답도 기록합니다 — 이 서버는 이를 오류가 아닌 성공적인 전체 0 본문으로 반환하므로 일반 .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개의 단위 테스트가 검증 규칙, 위험 휴리스틱, 그래프 검색, 물류, 예보 텍스트 파서(잘못된 입력 포함), 검토 중 발견된 모든 계약 및 정확성 버그에 대한 회귀 테스트를 다룹니다.

문서

**문서 색인**에서 시작하세요.

스크립트