trekking-mcp

English

Server Model Context Protocol (revisione della spec 2026-07-28, SDK Python mcp 2.x) per l'escursionismo sulle Alpi e sugli Appennini italiani: sentieri numerati, rifugi e bivacchi, bollettini valanghe e meteo di quota, esposti a un assistente AI come tool, resource e prompt.

Avvertenza. I bollettini valanghe sono documenti ufficiali di sicurezza. Questo progetto li rilegge e li normalizza, non li interpreta e non produce valutazioni del rischio. Non sostituisce il bollettino integrale, la formazione specifica, ne' il giudizio sul terreno. Usalo per preparare una gita, mai per decidere se farla.

Cosa mostra questo repo

Non e' un wrapper 1:1 su una API. Copre i tre primitivi del protocollo e un paio di meccanismi che si vedono raramente:

Installazione

uvx trekking-mcp

Nessuna API key richiesta: tutte le fonti di default sono aperte.

Per contribuire o sviluppare dal clone:

git clone https://github.com/19Alma98/trekking_mcp
cd trekking_mcp
uv sync            # oppure: pip install -e ".[dev]"

Uso con Claude Desktop / Claude Code

{
  "mcpServers": {
    "trekking": {
      "command": "uvx",
      "args": ["trekking-mcp"]
    }
  }
}

In alternativa, come server remoto:

trekking-mcp --transport http --port 8000            # solo 127.0.0.1

# esposto ad altre macchine: va dichiarato chi puo' chiamare
trekking-mcp --transport http --host 0.0.0.0 \
  --allow-host trekking.example.org:* \
  --allow-origin https://app.example.org

# con piu' repliche: le chiavi che sigillano il requestState vanno condivise,
# altrimenti un'elicitation iniziata su una replica muore sull'altra
export TREKKING_MCP_STATE_KEYS="$(python -c 'import secrets; print(secrets.token_hex(32))')"

# produzione: non usare overpass-api.de; alza la concorrenza solo sul tuo mirror
export OVERPASS_URL="https://overpass.example.org/api/interpreter"
# export OVERPASS_CONCURRENCY=4

Il secondo comando senza --allow-host viene rifiutato: l'SDK attiva la protezione da DNS rebinding solo quando il bind e' su localhost, cioe' proprio quando non serve. Vedi DEVELOPMENT.md §3.18.

Su HTTP l'accesso resta aperto (nessuna API key obbligatoria): un tetto per IP (HTTP_RATE_LIMIT_RPM / HTTP_RATE_LIMIT_BURST) limita tools/call e la lettura dei bollettini. Dietro un reverse proxy che riscrive X-Forwarded-For, imposta HTTP_TRUST_PROXY=1 cosi' il tetto e' per client e non per IP del proxy. Su stdio il limite non si applica. Vedi DEVELOPMENT.md §3.35.

Docker

docker build -t trekking-mcp .
docker run --rm -p 8000:8000 trekking-mcp
# health: curl -s localhost:8000/health
# MCP:   http://localhost:8000/mcp

L'immagine ascolta su 0.0.0.0:8000 con --allow-host per localhost e 127.0.0.1. Per un dominio pubblico passa gli argomenti dopo l'immagine, ad es. docker run --rm -p 8000:8000 trekking-mcp trekking-mcp --transport http --host 0.0.0.0 --port 8000 --allow-host 'trekking.example.org:*'.

Tool disponibili

meteo_quota non risponde con le prime ore della serie di Open-Meteo, che comincia a mezzanotte: parte dall'ora corrente se la data e' oggi, dalle 6 se e' un giorno futuro, e da ora_inizio se lo si indica. Una gita non si prepara guardando la notte. Vedi DEVELOPMENT.md §3.27.

Il flusso tipico non richiede che l'utente conosca un solo codice. Quando il punto di arrivo e' un nome, sentieri_verso_localita fa da solo geocoding, ricerca sentieri e rifugi: e' l'ingresso che le instructions del server indicano per primo, al posto della catena cerca_localita + cerca_sentieri. Da li', valuta_gita per il resto. La zona del bollettino viene dedotta dalle coordinate.

Le resource sono scala://pericolo-valanghe, scala://difficolta-escursionistica, metriche://fonti (latenza, errori e hit rate per fonte) e la template bollettino://{provider}/{zona_id}, i cui due argomenti si autocompletano: scelto slf, zona_id propone solo le zone svizzere.

L'elicitation, in breve

valuta_gita ha bisogno di sapere che difficolta' regge il gruppo e se ha ARTVA, pala e sonda. Sono informazioni che il modello non puo' dedurre e che non deve inventare. Il parametro e' annotato cosi':

profilo: Annotated[ProfiloUscita, Resolve(chiedi_profilo)]

Il parametro non compare nello schema di input del tool, quindi il modello non sa nemmeno che esiste. Prima di eseguire il corpo, il framework esegue il resolver, che restituisce un marker Elicit[ProfiloUscita]: la domanda viene inoltrata al client, l'utente risponde, il valore viene iniettato. Se l'utente rifiuta, la chiamata si interrompe.

Fonti dati e attribuzioni

I sentieri numerati CAI sono mappati dalla community OSM: questo progetto non accede ad alcun dato proprietario del Club Alpino Italiano, che non espone un'API pubblica. La copertura non e' uniforme e l'assenza di un sentiero non significa che non esista.

Sviluppo

uv run pytest              # test
uv run ruff check .        # lint
uv run ruff format --check .
uv run mypy                # type check
uv run python client/ispeziona.py   # client MCP minimale: elenca tool e resource

Sono gli stessi comandi che gira la CI, sulla stessa risoluzione: uv.lock e' versionato e la CI installa con uv sync --frozen, quindi le versioni degli strumenti sono identiche a quelle locali.

Architettura, decisioni di progetto e roadmap: DEVELOPMENT.md.

Licenza

MIT.