# Infoparcelle MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-SDK_1.22-green)](https://modelcontextprotocol.io)

> Serveur MCP (Model Context Protocol) de haute qualité pour l'API Infoparcelle - Accès aux données foncières, cadastrales et immobilières françaises.

## 📖 Vue d'ensemble

Ce serveur MCP permet aux LLMs d'interagir avec l'[API Infoparcelle](https://www.infoparcelle.fr), une plateforme qui agrège et structure des données publiques françaises provenant de multiples sources officielles (DGFiP, ADEME, Géorisques, INPI, INSEE).

### Données disponibles

- **Géocodage** : Recherche d'adresses, géocodage inversé, coordonnées GPS
- **Parcelles cadastrales** : Recherche avancée, superficies, contours, propriétaires
- **Municipalités** : Informations sur les communes françaises
- **Transactions immobilières (DVF)** : Prix de vente réels, historique des transactions
- **Diagnostics énergétiques (DPE)** : Classes énergétiques, consommations, émissions GES
- **Plans Locaux d'Urbanisme (PLU)** : Zones d'urbanisme, règles de construction, documents officiels
- **Permis de construire** : Autorisations d'urbanisme, projets de construction
- **Propriétaires** : Personnes morales propriétaires de biens immobiliers (entreprises, organismes)
- **Copropriétés** : Registre national des copropriétés, syndics, lots
- **Occupants** : Établissements et entreprises présents sur les parcelles (SIRENE)

## ⚡ Démarrage rapide et dépannage

**→ Voir [EXPLOITATION.md](EXPLOITATION.md)** : démarrage en développement (avec
ngrok), déploiement en production, et diagnostic des problèmes de connexion.

En cas de « le connecteur ne se connecte plus », les trois contrôles à faire dans
l'ordre :

```bash
U=https://<url-du-mcp>
curl -s $U/health                                                              # 1. le serveur répond
curl -s $U/.well-known/oauth-authorization-server | grep -o '"issuer":"[^"]*"'  # 2. il s'annonce sous la BONNE adresse
curl -s -D - -o /dev/null -X POST $U/mcp -H 'Content-Type: application/json' -d '{}' | grep -i www-authenticate   # 3. le 401 indique où s'authentifier
```

Si le point 2 renvoie `localhost` ou une ancienne URL : `MCP_PUBLIC_URL` a été
renseignée à tort, la retirer (le serveur déduit son adresse de l'appel reçu).

## 🚀 Installation

### Prérequis

- Node.js >= 18.0.0
- npm ou yarn
- Une clé API Infoparcelle (obtenir sur [infoparcelle.fr/compte/api](https://www.infoparcelle.fr/compte/api))

### Installation des dépendances

```bash
npm install
```

### Compilation

```bash
npm run build
```

## ⚙️ Configuration

### 1. Authentification

Le serveur MCP supporte **deux méthodes d'authentification**. Vous devez choisir l'une des deux options :

#### Option 1 : Clé API (recommandée pour la simplicité)

La clé API est la méthode la plus simple pour démarrer rapidement.

1. Créez un compte sur [https://www.infoparcelle.fr](https://www.infoparcelle.fr)
2. Accédez à [https://www.infoparcelle.fr/compte/api](https://www.infoparcelle.fr/compte/api)
3. Générez une nouvelle clé API
4. Définissez la variable d'environnement :

```bash
export INFOPARCELLE_API_KEY="votre_cle_api_ici"
```

Pour une configuration permanente, ajoutez cette ligne à votre `~/.bashrc` ou `~/.zshrc`.

#### Option 2 : OAuth Client Credentials (recommandée pour la production)

Cette méthode utilise le flux OAuth 2.0 Client Credentials pour obtenir automatiquement un token d'accès.

1. Créez un client OAuth dans Laravel Passport
2. Définissez les variables d'environnement :

```bash
export INFOPARCELLE_CLIENT_ID="votre_client_id"
export INFOPARCELLE_CLIENT_SECRET="votre_client_secret"
export LARAVEL_APP_URL="http://app.devinfoparcelle.fr"  # URL de votre application Laravel
```

**Note importante** :
- Le token est automatiquement obtenu et renouvelé quand il expire
- Le serveur MCP appelle `/oauth/token` avec `grant_type=client_credentials`
- Cette méthode est idéale pour les environnements de production
- Le client OAuth doit avoir les scopes appropriés pour accéder à l'API Infoparcelle

### 2. Choisir le mode de transport

Le serveur supporte deux modes de transport :

#### Mode stdio (par défaut)
Utilisé pour l'intégration avec Claude Desktop et autres clients MCP locaux.

```bash
# Pas de configuration nécessaire, c'est le mode par défaut
npm run inspector
```

#### Mode HTTP
Utilisé pour les déploiements distants et les serveurs accessibles via HTTP.

```bash
# Définir le mode de transport en HTTP
export MCP_TRANSPORT=http

# Optionnel : changer le port (défaut: 3000)
export PORT=8080

# Démarrer le serveur
node build/index.js
```

Le serveur HTTP expose les endpoints suivants :
- `POST /mcp` - Endpoint principal MCP (Streamable HTTP)
- `GET /mcp` - Endpoint pour les événements SSE (Server-Sent Events)
- `GET /health` - Health check du serveur
- `POST /oauth/token` - Obtenir un token d'accès OAuth (si authentification activée)
- `GET /authorize` - Page de connexion OAuth (mode standalone)
- `GET /previews/:fileId` - Servir les images de preview de parcelles
- `GET /.well-known/oauth-authorization-server` - Découverte OAuth (RFC 8414)
- `POST /register` - Enregistrement dynamique de clients OAuth (RFC 7591)

##### Authentification OAuth (mode HTTP)

Par défaut, le serveur HTTP utilise l'authentification OAuth 2.0 avec une page de connexion simple et sécurisée.

**⚠️ IMPORTANT : Flux d'authentification simplifié**

Les utilisateurs se connectent avec **leurs propres identifiants Infoparcelle** (email/mot de passe ou clé API) via une page de connexion moderne et sécurisée.

**Démarrage du serveur :**

```bash
# Démarrer en mode HTTP avec OAuth
MCP_TRANSPORT=http PORT=3000 node build/index.js
```

Au démarrage, le serveur affichera :
```
🔐 Authentification OAuth activée
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📖 Configuration dans Claude Desktop:

   1. Ouvrez Claude > Paramètres > Connecteurs
   2. Cliquez sur "Ajouter un connecteur personnalisé"
   3. Configurez :
      • Nom: Infoparcelle MCP
      • URL: http://localhost:3000/mcp
      • OAuth Client ID: any (ex: "infoparcelle")
      • OAuth Client Secret: any (ex: "secret")
   4. Cliquez sur "Se connecter"
   5. Connectez-vous avec votre email/mot de passe Infoparcelle

   Note: Les champs Client ID/Secret ne sont pas utilisés.
   Vous vous authentifierez via le formulaire de connexion.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**Configuration dans Claude Desktop :**

1. **Ouvrez Claude Desktop** > Paramètres > Connecteurs
2. **Cliquez** sur "Ajouter un connecteur personnalisé"
3. **Remplissez** :
   - **Nom** : Infoparcelle MCP
   - **URL** : `http://localhost:3000/mcp` (ou votre URL ngrok/publique)
   - **OAuth Client ID** : `infoparcelle` (valeur factice, ignorée)
   - **OAuth Client Secret** : `secret` (valeur factice, ignorée)
4. **Cliquez** sur "Se connecter"
5. **Une page de connexion s'ouvre** : Connectez-vous avec :
   - **Option 1 (recommandée)** : Votre email/mot de passe Infoparcelle
   - **Option 2** : Votre clé API Infoparcelle

**Comment ça marche ?**

1. L'utilisateur configure le connecteur dans Claude Desktop
2. Claude Desktop ouvre la page `/authorize` dans le navigateur
3. L'utilisateur se connecte avec ses identifiants Infoparcelle (email/password ou API key)
4. Le serveur valide les credentials via `/api/v1/token` de l'API Infoparcelle
5. Si valide : le serveur génère un code d'autorisation et redirige vers Claude
6. Claude échange le code contre un token MCP
7. Claude utilise ce token pour accéder aux outils MCP

**Tester la page de connexion :**

Ouvrez votre navigateur et accédez à :
```
http://localhost:3000/authorize?response_type=code&client_id=test&redirect_uri=http://localhost:3000/callback&code_challenge=test&code_challenge_method=S256
```

Vous verrez la page de connexion où vous pouvez vous authentifier avec :
- Email/mot de passe Infoparcelle
- Clé API Infoparcelle

**Mode avancé : Proxy Laravel Passport**

Si vous avez déjà une application Laravel avec Passport configuré, vous pouvez utiliser le mode proxy pour déléguer l'authentification OAuth à Laravel :

```bash
# Activer le mode proxy Laravel
export LARAVEL_APP_URL="http://app.devinfoparcelle.fr"
export MCP_PUBLIC_URL="https://votre-domaine.ngrok.app"

# Démarrer le serveur
MCP_TRANSPORT=http node build/index.js
```

Dans ce mode :
- Les utilisateurs s'authentifient directement sur votre application Laravel
- Le MCP agit comme un proxy OAuth entre Claude et Laravel
- Nécessite un client OAuth configuré dans Laravel Passport
- Redirect URI à configurer : `${MCP_PUBLIC_URL}/oauth/callback`

**Désactiver l'authentification OAuth :**

Si vous préférez désactiver l'authentification (non recommandé en production) :

```bash
export OAUTH_ENABLED=false
MCP_TRANSPORT=http node build/index.js
```

**Options avancées :**

```bash
# Durée de validité du token MCP en secondes (défaut: 3600 = 1h)
export OAUTH_TOKEN_EXPIRY=7200

# Secret de session pour stocker les credentials (défaut: auto-généré)
# ⚠️ IMPORTANT : Changez cette valeur en production !
export SESSION_SECRET="votre-secret-de-session-securise"

# Activer la vérification stricte du client_id lors de l'échange OAuth
# Par défaut désactivé pour compatibilité avec Claude Desktop
export OAUTH_STRICT_CLIENT_ID_CHECK=true

# Démarrer le serveur
MCP_TRANSPORT=http node build/index.js
```

## 🧪 Test avec MCP Inspector

Pour tester le serveur interactivement :

```bash
npm run inspector
```

Cela lancera le MCP Inspector qui vous permet de :
- Lister tous les outils disponibles
- Tester chaque outil avec des paramètres personnalisés
- Voir les réponses formatées

## 📦 Utilisation avec Claude Desktop

### Configuration

Ajoutez la configuration suivante à votre fichier `claude_desktop_config.json` :

**Emplacement du fichier :**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

**Configuration avec clé API (Option 1) :**

```json
{
  "mcpServers": {
    "infoparcelle": {
      "command": "node",
      "args": ["/chemin/absolu/vers/Infoparcelle-MCP/build/index.js"],
      "env": {
        "INFOPARCELLE_API_KEY": "votre_cle_api"
      }
    }
  }
}
```

**Configuration avec OAuth Client Credentials (Option 2) :**

```json
{
  "mcpServers": {
    "infoparcelle": {
      "command": "node",
      "args": ["/chemin/absolu/vers/Infoparcelle-MCP/build/index.js"],
      "env": {
        "INFOPARCELLE_CLIENT_ID": "votre_client_id",
        "INFOPARCELLE_CLIENT_SECRET": "votre_client_secret",
        "LARAVEL_APP_URL": "http://app.devinfoparcelle.fr"
      }
    }
  }
}
```

**Important :** Remplacez `/chemin/absolu/vers/Infoparcelle-MCP` par le chemin réel vers votre installation.

### Redémarrage

Redémarrez Claude Desktop pour que les changements prennent effet.

## 🛠️ Outils disponibles (14 outils)

### Géocodage (3 outils)

#### `infoparcelle_geocoder_search`
Recherche d'adresses françaises par texte libre.

**Exemple :**
```json
{
  "recherche": "7 Rue de l'Élysée 75008 Paris",
  "limite": 5
}
```

#### `infoparcelle_geocoder_ban`
Récupération d'une adresse par son identifiant BAN.

#### `infoparcelle_geocoder_coordinates`
Géocodage inversé : coordonnées GPS → parcelle cadastrale.

**Exemple :**
```json
{
  "lat": 48.8566,
  "lon": 2.3522
}
```

### Parcelles cadastrales (3 outils)

#### `infoparcelle_parcelle_get`
Obtenir la fiche complète d'une parcelle par son identifiant.

**Exemple :**
```json
{
  "cadastre_id": "750560000B0064",
  "geometrie": "contour"
}
```

#### `infoparcelle_parcelles_search`
Recherche avancée de parcelles avec des dizaines de filtres.

**Exemple - Terrains constructibles > 500m² à Paris :**
```json
{
  "code_municipalite": "75056",
  "superficie_min": 500,
  "plu_zone": "U"
}
```

**Exemple - Maisons avec bon DPE dans le 92 :**
```json
{
  "code_departement": "92",
  "bati_type": "DUR",
  "dpe_classe_energie": "A,B,C"
}
```

#### `infoparcelle_parcelle_preview`
Générer une prévisualisation SVG interactive d'une ou plusieurs parcelles.

**Exemple - Rendu réaliste avec annotations :**
```json
{
  "cadastre_id": "750560000B0064",
  "theme": "realisme_terrain",
  "afficher_surface": true,
  "afficher_numero_parcelle": true
}
```

**Exemple - Plan technique pour architecte :**
```json
{
  "cadastre_id": "750560000B0064",
  "theme": "architecte_blueprint",
  "width": 1920,
  "height": 1080,
  "dpi": 300,
  "afficher_mesures": true,
  "afficher_echelle": true,
  "echelle": "500"
}
```

**Exemple - Comparaison de plusieurs parcelles :**
```json
{
  "cadastre_id": "750560000B0064,750560000B0065,750560000B0066",
  "theme": "cadastre_plan"
}
```

### Territoires (1 outil)

#### `infoparcelle_municipalites_search`
Recherche de communes françaises.

**Exemple :**
```json
{
  "nom": "Paris"
}
```

### Transactions immobilières - DVF (1 outil)

#### `infoparcelle_dvf_search`
Recherche de transactions immobilières avec prix réels.

**Exemple - Transactions récentes dans le 75008 :**
```json
{
  "code_postal": "75008",
  "date_min": "2023-01-01",
  "limite": 20
}
```

**Exemple - Maisons entre 300k€ et 500k€ :**
```json
{
  "code_departement": "69",
  "type_local": "MAISON",
  "prix_min": 300000,
  "prix_max": 500000
}
```

### Diagnostics énergétiques - DPE (1 outil)

#### `infoparcelle_dpe_search`
Recherche de diagnostics de performance énergétique.

**Exemple - Logements performants (A-B) à Paris :**
```json
{
  "code_municipalite": "75056",
  "classe_energie": "A,B"
}
```

**Exemple - Passoires énergétiques (F-G) :**
```json
{
  "code_departement": "69",
  "classe_energie": "F,G"
}
```

### Plans Locaux d'Urbanisme - PLU (1 outil)

#### `infoparcelle_plu_search`
Recherche de zones PLU avec leurs documents officiels.

**Exemple - Zones constructibles à Paris :**
```json
{
  "code_municipalite": "75056",
  "zone": "U",
  "limite": 10
}
```

**Exemple - Zones agricoles dans le département 69 :**
```json
{
  "code_departement": "69",
  "zone": "A"
}
```

### Autorisations d'urbanisme - Permis (1 outil)

#### `infoparcelle_permis_search`
Recherche de permis de construire et autorisations d'urbanisme.

**Exemple - Permis de construire récents à Lyon :**
```json
{
  "code_municipalite": "69123",
  "type_autorisation": "PC",
  "date_autorisation_min": "2023-01-01",
  "limite": 20
}
```

**Exemple - Projets avec création de logements :**
```json
{
  "code_departement": "75",
  "nb_logements_crees_min": 5,
  "etat": 2
}
```

### Propriétaires (1 outil)

#### `infoparcelle_proprietaires_search`
Recherche de propriétaires personnes morales (entreprises, organismes publics).

**Exemple - Recherche par SIREN :**
```json
{
  "siren": "552032534"
}
```

**Exemple - SCI propriétaires dans le 75 :**
```json
{
  "code_postal": "75008",
  "forme_juridique_abreviation": "SCI",
  "limite": 20
}
```

### Copropriétés (1 outil)

#### `infoparcelle_coproprietes_search`
Recherche de copropriétés immatriculées au registre national.

**Exemple - Grandes copropriétés à Paris :**
```json
{
  "code_municipalite": "75056",
  "nb_lot_min": 50,
  "type_syndic": 2
}
```

**Exemple - Copropriétés avec syndic bénévole :**
```json
{
  "code_departement": "69",
  "type_syndic": 1
}
```

### Occupants (1 outil)

#### `infoparcelle_occupants_search`
Recherche d'établissements et entreprises présents sur les parcelles (données SIRENE).

**Exemple - Commerces actifs sur une parcelle :**
```json
{
  "code_parcelle": "750560000B0064",
  "etat_administratif": 0
}
```

**Exemple - Restaurants dans le 75008 :**
```json
{
  "code_postal": "75008",
  "naf_section": "I",
  "etat_administratif": 0,
  "limite": 20
}
```

## 🎯 Cas d'usage

### Recherche immobilière

```
"Trouve-moi des terrains constructibles de plus de 1000m²
dans le département 69 avec un bon accès (à moins de 500m d'une route)"
```

### Analyse de marché

```
"Analyse les transactions immobilières d'appartements à Lyon
au cours des 12 derniers mois et donne-moi le prix moyen au m²"
```

### Étude énergétique

```
"Combien y a-t-il de passoires énergétiques (DPE F ou G)
dans la commune de Marseille ?"
```

### Investissement

```
"Trouve des maisons avec un bon DPE (A, B ou C),
vendues récemment entre 200k€ et 400k€ dans le Rhône"
```

### Étude d'urbanisme

```
"Quelles sont les règles d'urbanisme applicables à cette parcelle ?
Montre-moi les zones PLU et les documents règlementaires"
```

### Veille sur les projets de construction

```
"Liste tous les permis de construire déposés dans ma commune
au cours des 6 derniers mois avec création de plus de 10 logements"
```

### Analyse patrimoniale

```
"Identifie toutes les parcelles détenues par cette SCI (SIREN 123456789)
dans le département 75 et donne-moi leur superficie totale"
```

### Étude de copropriétés

```
"Trouve les copropriétés de plus de 100 lots avec syndic professionnel
dans le 8ème arrondissement de Paris"
```

### Analyse commerciale

```
"Liste tous les commerces et restaurants actifs
sur les parcelles de cette rue (code postal 75008)"
```

## 📊 Données et sources

Les données proviennent de sources officielles françaises :

- **DGFiP** : Données cadastrales, transactions (DVF), propriétaires
- **ADEME** : Diagnostics de Performance Énergétique (DPE)
- **INSEE** : Codes communes, populations, données SIRENE (occupants)
- **IGN** : Géométries, contours
- **Géorisques** : Risques naturels
- **ANAH** : Registre national des copropriétés
- **Ministère de la Transition Écologique** : Plans Locaux d'Urbanisme (PLU)
- **SITADEL** : Permis de construire et autorisations d'urbanisme
- **INPI** : Données des entreprises

## 🔐 Sécurité et confidentialité

- **Authentification** : Clé API Bearer Token
- **Rate limiting** : 1200 requêtes/minute (20 req/sec)
- **Données publiques** : Toutes les données sont publiques et officielles
- **Pas de stockage** : Le serveur ne stocke aucune donnée

## 📝 Développement

### Structure du projet

```
Infoparcelle-MCP/
├── src/
│   ├── index.ts                    # Point d'entrée du serveur MCP
│   ├── schemas/                    # Schémas de validation Zod
│   │   ├── geocoding.ts            # Schémas pour le géocodage
│   │   ├── parcelles.ts            # Schémas pour les parcelles (requêtes simples)
│   │   ├── parcelles-advanced.ts   # Schémas pour la recherche avancée de parcelles
│   │   ├── territoires.ts          # Schémas pour les territoires/municipalités
│   │   ├── dvf.ts                  # Schémas pour les transactions DVF
│   │   ├── dpe.ts                  # Schémas pour les diagnostics énergétiques
│   │   ├── plu.ts                  # Schémas pour les PLU
│   │   ├── permis.ts               # Schémas pour les permis de construire
│   │   ├── proprietaires.ts        # Schémas pour les propriétaires
│   │   ├── coproprietes.ts         # Schémas pour les copropriétés
│   │   └── occupants.ts            # Schémas pour les occupants SIRENE
│   ├── tools/                      # Implémentation des outils MCP (14 outils)
│   │   ├── geocoding.ts            # Outils de géocodage (3 outils)
│   │   ├── parcelles.ts            # Outils parcelles cadastrales (3 outils)
│   │   ├── territoires.ts          # Outils territoires (1 outil)
│   │   ├── dvf.ts                  # Outils transactions DVF (1 outil)
│   │   ├── dpe.ts                  # Outils diagnostics DPE (1 outil)
│   │   ├── plu.ts                  # Outils PLU (1 outil)
│   │   ├── permis.ts               # Outils permis de construire (1 outil)
│   │   ├── proprietaires.ts        # Outils propriétaires (1 outil)
│   │   ├── coproprietes.ts         # Outils copropriétés (1 outil)
│   │   └── occupants.ts            # Outils occupants SIRENE (1 outil)
│   └── utils/                      # Utilitaires partagés
│       ├── api-client.ts           # Client HTTP pour l'API Infoparcelle
│       ├── oauth.ts                # Gestionnaire OAuth standalone
│       ├── laravel-oauth-proxy.ts  # Proxy OAuth vers Laravel Passport
│       ├── temp-storage.ts         # Stockage temporaire pour les previews
│       ├── errors.ts               # Gestion centralisée des erreurs
│       └── formatting.ts           # Formatage des réponses MCP
├── .temp-previews/                 # Stockage temporaire des images (auto-généré)
├── build/                          # Code TypeScript compilé
├── package.json                    # Dépendances et scripts npm
├── tsconfig.json                   # Configuration TypeScript
└── README.md                       # Documentation principale
```

### Scripts disponibles

```bash
# Compilation
npm run build

# Compilation en mode watch
npm run dev

# Test avec MCP Inspector
npm run inspector

# Nettoyage
npm run clean
```

### Ajouter un nouvel outil

1. Créer le schéma Zod dans `src/schemas/`
2. Implémenter l'outil dans `src/tools/`
3. Importer et ajouter l'outil dans `src/index.ts`
4. Recompiler avec `npm run build`

## 🤝 Contribution

Les contributions sont les bienvenues ! Pour contribuer :

1. Forkez le projet
2. Créez une branche pour votre fonctionnalité
3. Committez vos changements
4. Poussez vers la branche
5. Ouvrez une Pull Request

## 📄 Licence

Ce projet est sous licence MIT. Voir le fichier [LICENSE](LICENSE) pour plus de détails.

## 🔗 Liens utiles

- [API Infoparcelle](https://www.infoparcelle.fr)
- [Documentation API](https://www.infoparcelle.fr/documentation)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Claude Desktop](https://claude.ai)
- [MCP SDK](https://github.com/anthropics/mcp-sdk)

## ❓ Support

Pour toute question ou problème :

- **API Infoparcelle** : [support@infoparcelle.fr](mailto:support@infoparcelle.fr)
- **Issues GitHub** : [Ouvrir une issue](https://github.com/Julio-rootsud/Infoparcelle-MCP/issues)

## 🎉 Remerciements

Merci à l'équipe Infoparcelle pour la mise à disposition de cette API de qualité donnant accès aux données publiques françaises de manière structurée et performante.

---

Fait avec ❤️ pour la communauté MCP