TrailSmith – wetterbewusster Karpaten-Reiseplanungs-Agent (MCP-Aufgabe)

Repository: https://github.com/mashta-lilia/trailsmith-mcp-agent (vollständiger Commit-Verlauf; dieses Archiv ist ein Export der versionierten Dateien zu einem bestimmten Commit)

Ein domänenspezifischer Daten-Agent, der mehrtägige Wanderrouten in der Tschornohora-Region validiert, risikobewertet und neu plant. Er nutzt zwei MCP-Verbindungen:

• Bestehender Server (Teil A): OpenWeather MCP – Live-5-Tage-Wettervorhersagen pro Ortschaft.

• Eigener Server (Teil B): trailsmith (dieses Repository, trailsmith_mcp/) – vier Domänen-Tools über einem lokalen, kuratierten Wegedatensatz.

Der Agent (Claude Agent SDK) validiert eine Route, erzeugt pro Tag einen Tagesbewertungs-Subagenten parallel (Vorhersage → deterministische Analyse → Risikobewertung), erzeugt Neuplanungs-Subagenten für no_go-Tage, führt die Ergebnisse zusammen und validiert erneut, und erstellt einen finalen Plan mit einer sichtbaren Wertschöpfungskette vom rohen Vorhersagetext bis zur Entscheidung.

Schnellstart in einem Befehl (keine API-Schlüssel nötig)

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

Das führt den gesamten Planungsablauf gegen eine aufgezeichnete Vorhersage aus – validieren, jeden Tag bewerten, den gefährlichen Tag neu planen, Logistik schätzen – ohne LLM und ohne Anmeldedaten:

[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]

Vollständige Anleitung mit Live-Wetter und dem Agenten: docs/quickstart.md.

Related MCP server: GemmaJnana

Voraussetzungen

• Python 3.12+ (getestet mit 3.13)

• Go 1.21+ (nur zum Erstellen des OpenWeather-MCP-Binaries)

• Ein OpenWeatherMap-API-Schlüssel (kostenlose Stufe) und ein Anthropic-API-Schlüssel

Installation

PowerShell, vom Repository-Stammverzeichnis aus:

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

Dann .env bearbeiten:

Geheimnisse leben ausschließlich in .env (git-ignoriert, zusammen mit allen .env.*-Varianten). Es wird nichts Sensibles eingecheckt.

Unabhängige Startbefehle

• Eigener MCP-Server (separater Prozess): .\.venv\Scripts\python -m trailsmith_mcp

• Agent: .\.venv\Scripts\python -m agent.runner demo\itinerary_clean.json

• Smoke-Tests: .\.venv\Scripts\python scripts\smoke_custom_server.py (erkennt und ruft den eigenen Server über stdio auf), .\.venv\Scripts\python scripts\smoke_weather_server.py [city] (bestehender Server).

Der Agent startet seine eigenen MCP-Verbindungen; das manuelle Starten von trailsmith_mcp demonstriert Prozess­trennung und unabhängige Startbarkeit.

Demo-Eingaben

**Vor einer Live-Demo scripts/refresh_demo.py ausführen** – es verschiebt die Demo-Daten in das Vorhersagefenster, zeichnet echte Fixtures neu auf, erstellt das datumsgebundene Sturmszenario neu und gibt die Demo-Befehle aus.

Die Demo-Daten müssen innerhalb des 5-Tage-Vorhersagefensters liegen. Sie sind auf den 20.08.2026 gesetzt; vor einer Live-Demo jedes date-Feld anpassen und scripts/fetch_fixtures.py erneut ausführen. Außerhalb des Fensters wirft der Parser korrekt NO_FORECAST_FOR_DATE und der Tag wird auf weather_known=false / caution herabgestuft – ein legitimer Pfad, aber nicht der, den man als sauberen Durchlauf präsentieren möchte.

Fixtures und Offline-Wiedergabe

• Echte Antworten aufzeichnen: .\.venv\Scripts\python scripts\fetch_fixtures.py speichert den rohen Tool-Text unter fixtures/openweather/. Es zeichnet auch die Antwort für eine ungültige Stadt auf – die der Server als erfolgreichen Alles-Nullen-Body zurückgibt, nicht als Fehler, also als normale .txt gespeichert. Es gibt keine .error.txt-Fixtures, weil der vorgelagerte Server nie einen Fehler erzeugt hat.

• Offline-Wiedergabe: REPLAY=1 setzen und den Agenten normal ausführen. Der Wiedergabeserver (scripts/replay_weather_server.py) bietet denselben weather-Vertrag an und liefert den aufgezeichneten Text unverändert aus – die Analyse- und Fehlerbehandlung des Agenten läuft unverändert; nichts wird vorab geparst.

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

• Sturmszenario. no_go-Risiko erfordert Gewitter oder schwere Wetterbedingungen, die in Karpaten-Vorhersagen oft fehlen – an einem ruhigen Tag meldet der Agent korrekt ok/caution und plant nie neu, sodass der Neuplanungszweig nicht auf Abruf demonstriert werden kann. fixtures/scenario_storm/ enthält eine klar gekennzeichnete synthetische Eingabe (eine geänderte Wetterbedingung in einer ansonsten echten Aufzeichnung), um diesen Zweig zu testen; siehe dessen README, und weisen Sie bei der Vorführung darauf hin. Auswählen mit:

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

Ratenlimits

Der kostenlose OpenWeatherMap-Tarif erlaubt 60 Aufrufe/Minute. Was unsere Aufrufmenge tatsächlich begrenzt:

• validate_itinerary lehnt Routen mit mehr als 7 Tagen ab (Itinerary.days hat max_length=7), sodass höchstens 7 Tagesbewertungs-Subagenten erzeugt werden.

• Jeder Tagesbewertungs-Subagent ist auf maxTurns=6 begrenzt, sodass er bei einem Fehler nicht in einer Schleife auf die Wetter-API zugreifen kann.

• Der ungünstigste Fall liegt damit deutlich unter dem Minutenlimit. Die Breite der parallelen Stapelverarbeitung entscheidet der Claude-Code-CLI-Task-Scheduler, nicht dieser Code – wir begrenzen die Gesamtzahl der Aufrufe, nicht deren Nebenläufigkeit.

Kostenbegrenzungen (agent/orchestrator.py): max_budget_usd=1.50 und max_turns=30 in der Hauptschleife, plus maxTurns pro Subagent. Dies sind harte SDK-Grenzen, keine Prompt-Anweisungen; agent/runner.py gibt die Anzahl der Turns und die Dollarkosten aus und kennzeichnet einen Lauf, der an einer Begrenzung gestoppt wurde.

Gesamtsystem verifizieren

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

Führt 12 Prüfungen aus – beide MCP-Verbindungen und deren Tool-Erkennung, Prozess­trennung, ein erfolgreicher Aufruf auf jeder Seite, strukturierter Fehler vs. leerer Erfolg, konservative Verschlechterung bei unbrauchbarer Vorhersage, byte-identische Datensatz-Regenerierung und die Testsuite. Keine Anthropic-Anmeldedaten erforderlich.

Tests

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

45 Unit-Tests decken Validierungsregeln, Risiko-Heuristiken, Graphsuche, Logistik, den Vorhersagetext-Parser (einschließlich fehlerhafter Eingaben) und Regressionstests für jeden Vertrags- und Korrektheitsfehler ab, der während der Überprüfung gefunden wurde.

Dokumentation

Beginnen Sie mit dem Dokumentationsindex.

Skripte