# geocodage-mcp

Serveur MCP (Model Context Protocol) connecté à l'**API de géocodage de la Géoplateforme (IGN)**.  
Permet de géocoder des adresses, lieux (POI) et parcelles cadastrales françaises en temps réel, ainsi que de faire du géocodage inverse.

> API publique, sans clé. Limite : 50 requêtes/seconde par IP.  
> Sources : BAN (adresses), BD TOPO® (POI), Parcellaire Express PCI (parcelles).

## Prérequis

- Node.js >= 18

## Installation

```bash
npm install
```

## Démarrage

```bash
node index.js
```

Le serveur communique via **stdio** et est prêt à être connecté à un client MCP.

## Outils exposés

### `geocode`

Géocodage direct via `GET https://data.geopf.fr/geocodage/search`.

**Paramètres principaux :**

| Nom | Type | Requis | Description |
|---|---|---|---|
| `q` | string | oui | Chaîne à géocoder (adresse, lieu, référence cadastrale) |
| `index` | string | non | Index : `address` (défaut), `poi`, `parcel` |
| `limit` | number | non | Nombre de résultats (1–50, défaut : 10) |
| `lat` / `lon` | number | non | Point de proximité pour favoriser les résultats proches |
| `autocomplete` | `"0"` / `"1"` | non | Active l'autocomplétion (défaut : `"1"`) |
| `returntruegeometry` | boolean | non | Retourne la vraie géométrie |
| `postcode` | string | non | Filtre code postal (address, poi) |
| `citycode` | string | non | Filtre code INSEE (address, poi) |
| `depcode` | string | non | Filtre code département (address, poi) |
| `type` | string | non | Type d'adresse : `housenumber`, `street`, `locality`, `municipality` |
| `city` | string | non | Filtre par commune |
| `category` | string | non | Filtre catégorie POI (poi uniquement) |
| `departmentcode` / `municipalitycode` / `section` / `number` / `sheet` | string | non | Filtres cadastraux (parcel uniquement) |

**Exemples de requêtes :**
- `q=10 rue de la Paix Paris`
- `q=cimetière Vincennes, index=poi`
- `q=75056104AE0003, index=parcel`

---

### `geocode_reverse`

Géocodage inverse via `GET https://data.geopf.fr/geocodage/reverse`.

**Paramètres principaux :**

| Nom | Type | Requis | Description |
|---|---|---|---|
| `lon` | number | oui* | Longitude du point de recherche |
| `lat` | number | oui* | Latitude du point de recherche |
| `searchgeom` | string | non | Géométrie JSON (Point, Circle, Polygon, LineString). Si fournie, `lon`/`lat` servent à l'ordonnancement |
| `index` | string | non | `address`, `poi`, `parcel` |
| `limit` | number | non | 1–50, défaut 10 |
| `type` | string | non | Filtre type d'adresse (address) |
| `city` / `postcode` / `citycode` | string | non | Filtres address/poi |
| `category` | string | non | Filtre catégorie POI |

\* Requis si `searchgeom` absent.

**Exemple Circle :**
```json
{ "type": "Circle", "coordinates": [2.294469, 48.858244], "radius": 100 }
```

---

### `geocode_capabilities`

Retourne les capacités de l'API via `GET https://data.geopf.fr/geocodage/getCapabilities` :
opérations disponibles, index, champs interrogeables, valeurs de catégories POI, etc.

Aucun paramètre requis.

---

## Structure du projet

```
geocodage-mcp/
├── index.js              # Entrée MCP : déclaration des outils + connexion stdio
├── package.json
└── src/
    ├── client.js         # Client HTTP fetch vers l'API Géoplateforme
    └── tools/
        ├── search.js     # Schéma Zod + handler geocode
        ├── reverse.js    # Schéma Zod + handler geocode_reverse
        └── capabilities.js  # Handler geocode_capabilities
```

## Intégration

```json
{
  "servers": {
    "geocodage": {
      "type": "stdio",
      "command": "node",
      "args": ["/chemin/vers/geocodage-mcp/index.js"]
    }
  }
}
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "geocodage": {
      "command": "node",
      "args": ["/chemin/vers/geocodage-mcp/index.js"]
    }
  }
}
```


## Exemple de recherche

Configuration :
![geocodage MCP Tools](geocodage-mcp-tools.png)

Requête initiale :

### `10 rue du chateau avec @mcp:geocodage: ?`

Used MCP tool: geocodage/geocode

En cherchant "10 rue du chateau" sans préciser de ville avec l'outil MCP `geocodage`, l'API retourne plusieurs correspondances possibles, car c'est une adresse très courante en France. 

Voici les 5 correspondances les plus pertinentes :

1.  **10 Rue du Château, 92600 Asnières-sur-Seine**
    *   Longitude : `2.28736`
    *   Latitude : `48.906493`
2.  **10 rue du Château, 29200 Brest**
    *   Longitude : `-4.490812`
    *   Latitude : `48.383654`
3.  **10 Rue du Château, 44000 Nantes**
    *   Longitude : `-1.552009`
    *   Latitude : `47.216291`
4.  **10 Rue du Chateau, 21000 Dijon**
    *   Longitude : `5.037218`
    *   Latitude : `47.323033`
5.  **10 Rue du Château, 92500 Rueil-Malmaison**
    *   Longitude : `2.180793`
    *   Latitude : `48.875649`

Souhaitez-vous préciser une ville ou un code postal pour affiner ce résultat, ou cherchez-vous les coordonnées d'une de ces villes en particulier ?

### `et à Seurre ?`

Pour le **10 Rue du Château à Seurre** (21250), l'outil MCP `geocodage` trouve bien cette adresse unique. Voici les coordonnées précises :

*   **Longitude :** `5.145836`
*   **Latitude :** `46.997484`

Si vous souhaitez visualiser cette position exacte sur une carte (avec un fort niveau de zoom), voici les liens d'accès direct correspondants :

*   **Google Maps :** [https://www.google.com/maps/@46.997484,5.145836,20z](https://www.google.com/maps/@46.997484,5.145836,20z)
*   **OpenStreetMap :** [https://www.openstreetmap.org/?mlat=46.997484&mlon=5.145836#map=19/46.997484/5.145836](https://www.openstreetmap.org/?mlat=46.997484&mlon=5.145836#map=19/46.997484/5.145836)
*   **Géoportail :** [https://www.geoportail.gouv.fr/carte?c=5.145836,46.997484&z=19](https://www.geoportail.gouv.fr/carte?c=5.145836,46.997484&z=19)