# GeoTrek MCP

Serveur MCP (Model Context Protocol) pour rechercher des treks (randonnées, VTT,
équestre, raquette, ...) sur une instance [GeoTrek](https://geotrek.fr/) via son
API publique v2, avec géocodage de lieux via [Nominatim](https://nominatim.org/).

## Outils exposés

- **`search_treks`** — recherche des treks selon la durée (h), le dénivelé
  positif (m), les labels de réglementation, le type d'activité, et la
  proximité d'un lieu (nom, géocodé via Nominatim) ou de coordonnées
  (`lat`/`lon` + `radius_km`).
- **`list_activities`** — liste les types d'activité (pratiques) de
  l'instance GeoTrek, à utiliser dans `search_treks(practice_names=...)`.
- **`list_labels`** — liste les labels de réglementation de l'instance
  GeoTrek, à utiliser dans `search_treks(label_names=...)`.

## Installation

```bash
pip install -e .
```

## Configuration

L'adresse de l'instance GeoTrek est un paramètre du serveur, fourni au
démarrage via variable d'environnement ou argument CLI :

```bash
export GEOTREK_BASE_URL="https://geotrek-admin.ecrins-parcnational.fr"
geotrek-mcp
# ou
geotrek-mcp --base-url https://geotrek-admin.ecrins-parcnational.fr
```

Variables/arguments optionnels :

- `NOMINATIM_URL` / `--nominatim-url` : instance Nominatim à utiliser pour le
  géocodage (défaut : `https://nominatim.openstreetmap.org`).
- `MCP_TRANSPORT` / `--transport` : `stdio` (défaut, usage local) ou
  `streamable-http` (serveur distant accessible en HTTP, voir ci-dessous).
- `MCP_HOST` / `--host` : adresse d'écoute pour `streamable-http` (défaut
  `0.0.0.0`).
- `MCP_PORT` / `--port` : port d'écoute pour `streamable-http` (défaut `8000`).

## Déploiement à distance (Claude.ai, ChatGPT, ...)

Pour être ajouté comme connecteur distant sur Claude.ai ou ChatGPT, le serveur
doit tourner en transport HTTP (pas `stdio`, qui n'est utilisable que par un
client lancé sur la même machine) et être exposé en HTTPS.

Sur votre serveur, après avoir cloné le dépôt et installé le package :

```bash
export GEOTREK_BASE_URL="https://geotrek-admin.ecrins-parcnational.fr"
export MCP_TRANSPORT=streamable-http
export MCP_HOST=0.0.0.0
export MCP_PORT=8000
geotrek-mcp
```

Le serveur écoute alors sur `http://0.0.0.0:8000/mcp`. Il vous reste à :

1. **Le garder en vie** : lancez-le via un gestionnaire de process
   (`systemd`, `supervisor`, `pm2`, un service Docker...) plutôt qu'un simple
   `&`/`nohup`, pour qu'il redémarre en cas de crash ou de reboot.
2. **Le mettre en HTTPS** : Claude.ai et ChatGPT exigent une URL en HTTPS
   pour les connecteurs distants. Mettez un reverse proxy devant (nginx,
   Caddy, Traefik...) qui termine le TLS et transfère vers
   `http://127.0.0.1:8000/mcp` (dans ce cas, faites plutôt écouter
   `geotrek-mcp` sur `127.0.0.1` uniquement, et laissez le reverse proxy être
   le seul point d'entrée public).
3. **Ajouter le connecteur** : dans Claude.ai (Réglages → Connecteurs →
   Ajouter un connecteur personnalisé) ou ChatGPT (mode développeur →
   Connecteurs), collez l'URL publique, ex.
   `https://mcp.mon-domaine.fr/mcp`. Aucune authentification n'est requise
   ici puisque le serveur ne fait que relayer des données déjà publiques.

Exemple minimal de `systemd` unit (`/etc/systemd/system/geotrek-mcp.service`) :

```ini
[Unit]
Description=GeoTrek MCP server
After=network.target

[Service]
Environment=GEOTREK_BASE_URL=https://geotrek-admin.ecrins-parcnational.fr
Environment=MCP_TRANSPORT=streamable-http
Environment=MCP_HOST=127.0.0.1
Environment=MCP_PORT=8000
ExecStart=/chemin/vers/GeoTrekMCP/.venv/bin/geotrek-mcp
Restart=on-failure
User=www-data

[Install]
WantedBy=multi-user.target
```

## Exemple de configuration MCP (Claude Desktop / Claude Code)

```json
{
  "mcpServers": {
    "geotrek": {
      "command": "geotrek-mcp",
      "env": {
        "GEOTREK_BASE_URL": "https://geotrek-admin.ecrins-parcnational.fr"
      }
    }
  }
}
```

## Développement

```bash
pip install -e ".[dev]" 2>/dev/null || pip install -e . pytest
pytest
```

Pour tester interactivement avec l'inspecteur MCP :

```bash
mcp dev geotrek_mcp/server.py
```