# mcp-datagouv 🇫🇷

Serveur [MCP](https://modelcontextprotocol.io) (Model Context Protocol) pour interroger les **Open Data** de [data.gouv.fr](https://www.data.gouv.fr), la plateforme ouverte des données publiques françaises.

**v2.0** — Cache, retry, rate limiting, agrégations, API Geo, API Adresse, prompts guidés, transport HTTP.

## Fonctionnalités

### 📊 Catalogue data.gouv.fr (20 outils)

| Outil | Description |
|-------|-------------|
| `search_datasets` | Recherche par mots-clés, tags, organisation, licence, badge |
| `get_dataset` | Détail complet d'un dataset |
| `list_dataset_resources` | Fichiers/ressources d'un dataset |
| `get_resource` | Détail d'une ressource |
| `download_resource_preview` | Aperçu du contenu d'un fichier (CSV, JSON, texte) |
| `search_organizations` | Recherche d'organisations |
| `get_organization` | Détail d'une organisation |
| `list_organization_datasets` | Datasets d'une organisation |
| `search_reuses` | Réutilisations de données |
| `get_tabular_meta` | Métadonnées tabulaires (colonnes, types) |
| `query_tabular_data` | Requête de données avec recherche textuelle |
| `query_tabular_data_filtered` | Requête avec filtres sur colonnes |
| `aggregate_tabular_data` | Statistiques (sum, avg, min, max, count, distinct) |
| `group_by_tabular_data` | GROUP BY + agrégation |
| `list_licenses` | Licences disponibles |
| `list_frequencies` | Fréquences de mise à jour |
| `search_tags` | Tags/thématiques |
| `cache_stats` | Statistiques du cache |
| `cache_clear` | Vider le cache |

### 🗺️ API Geo — Découpage administratif (5 outils)

| Outil | Description |
|-------|-------------|
| `search_communes` | Recherche par nom, code postal, département, GPS |
| `get_commune` | Détail d'une commune par code INSEE |
| `list_departements` | Liste des départements |
| `get_departement_communes` | Communes d'un département |
| `list_regions` | Liste des régions |

### 📍 API Adresse — Géocodage (2 outils)

| Outil | Description |
|-------|-------------|
| `geocode_address` | Adresse → coordonnées GPS |
| `reverse_geocode` | Coordonnées GPS → adresse |

### 💬 Prompts prédéfinis (5 prompts)

| Prompt | Description |
|--------|-------------|
| `analyse_dataset` | Workflow guidé : recherche → inspection → stats → synthèse |
| `explorer_organisation` | Explorer une organisation en profondeur |
| `trouver_donnees_territoire` | Trouver des données sur un territoire |
| `comparer_datasets` | Comparer deux jeux de données |
| `geocoder_adresses` | Géocoder une liste d'adresses |

### 📦 Resources MCP (3 resources)

| Resource | Description |
|----------|-------------|
| `datagouv://platform-info` | Documentation des APIs disponibles |
| `datagouv://server-config` | Configuration active du serveur |
| `datagouv://recent-datasets` | Datasets consultés durant la session |

## Installation

```bash
git clone <votre-repo>
cd mcp-datagouv
npm install
npm run build
```

## Configuration

Copiez `.env.example` en `.env` et ajustez les variables :

```bash
cp .env.example .env
```

Variables principales :

| Variable | Défaut | Description |
|----------|--------|-------------|
| `DATAGOUV_API_KEY` | — | Clé API (optionnel, pour écriture) |
| `MCP_TRANSPORT` | `stdio` | Transport : `stdio` ou `http` |
| `MCP_HTTP_PORT` | `3000` | Port HTTP |
| `MCP_LOG_LEVEL` | `info` | Niveau de log |
| `MCP_CACHE_TTL` | `300000` | Cache TTL par défaut (5 min) |
| `MCP_CACHE_TTL_REF` | `21600000` | Cache TTL référentiels (6h) |
| `MCP_MAX_RETRIES` | `3` | Retries sur erreurs transitoires |
| `MCP_ENABLE_GEO` | `true` | Module Geo |
| `MCP_ENABLE_ADRESSE` | `true` | Module Adresse |
| `MCP_TABULAR_RATE_LIMIT` | `80` | Rate limit API tabulaire (req/s) |
| `MCP_CATALOG_RATE_LIMIT` | `30` | Rate limit API catalogue (req/s) |

## Usage

### Claude Desktop

Fichier `claude_desktop_config.json` :

```json
{
  "mcpServers": {
    "datagouv": {
      "command": "node",
      "args": ["/chemin/absolu/vers/mcp-datagouv/build/index.js"],
      "env": {
        "MCP_LOG_LEVEL": "debug"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add datagouv node /chemin/absolu/vers/mcp-datagouv/build/index.js
```

### Transport HTTP (serveur distant)

```bash
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npm start
```

### Docker

```bash
docker build -t mcp-datagouv .
docker run -p 3000:3000 mcp-datagouv
```

## Exemples d'utilisation

```
"Recherche les données sur la qualité de l'air en Île-de-France"
"Montre-moi les datasets du Ministère de l'Intérieur"
"Quels sont les fichiers du dataset des prix du carburant ?"
"Affiche les premières lignes de ce CSV"
"Calcule la moyenne et le max de la colonne 'population'"
"Groupe les données par département et calcule la somme des habitants"
"Géocode l'adresse '8 bd du Port, Amiens'"
"Quelles communes se trouvent dans le département 59 ?"
"Liste les régions de France"
```

Avec les prompts :
```
"Utilise le prompt 'analyse_dataset' sur le sujet 'transport ferroviaire'"
"Utilise 'trouver_donnees_territoire' pour Lyon, thématique environnement"
```

## Robustesse

- **Cache mémoire** avec TTL configurable (5 min données, 6h référentiels)
- **Retry automatique** avec backoff exponentiel sur erreurs 429/5xx
- **Rate limiting** par domaine API (catalogue, tabulaire, geo, adresse)
- **Timeout** configurable avec abort
- **Logging structuré** sur stderr (compatible STDIO)

## Architecture

```
src/
├── index.ts              # Point d'entrée, transport STDIO/HTTP
├── config.ts             # Configuration via env
├── logger.ts             # Logger structuré (stderr)
├── cache.ts              # Cache mémoire TTL
├── rate-limiter.ts       # Rate limiter sliding window
├── http-client.ts        # Client HTTP (retry, cache, rate limit)
├── api-client.ts         # API data.gouv.fr (catalogue + tabulaire)
├── api-geo.ts            # API Découpage Administratif
├── api-adresse.ts        # API Adresse (géocodage)
├── formatters.ts         # Formatage des réponses
├── aggregations.ts       # Calculs statistiques
├── tools.ts              # Outils MCP catalogue
├── tools-geo.ts          # Outils MCP geo
├── tools-adresse.ts      # Outils MCP adresse
├── prompts.ts            # Prompts MCP prédéfinis
├── resources.ts          # Resources MCP dynamiques
└── __tests__/            # Tests unitaires
    ├── cache.test.ts
    ├── rate-limiter.test.ts
    ├── formatters.test.ts
    └── aggregations.test.ts
```

## Tests

```bash
# Tests avec Node.js >= 22 (strip-types natif)
npm test

# Ou après compilation
npm run test:build
```

## APIs utilisées

| API | URL | Authentification |
|-----|-----|------------------|
| Catalogue data.gouv.fr | `https://www.data.gouv.fr/api/1/` | Non (lecture) |
| API Tabulaire (beta) | `https://tabular-api.data.gouv.fr/api/` | Non |
| API Geo | `https://geo.api.gouv.fr/` | Non |
| API Adresse | `https://api-adresse.data.gouv.fr/` | Non |

## Licence

MIT