# nyambot-mcp

[![PyPI](https://img.shields.io/pypi/v/nyambot-mcp?color=2563eb)](https://pypi.org/project/nyambot-mcp/) [![Python](https://img.shields.io/pypi/pyversions/nyambot-mcp)](https://pypi.org/project/nyambot-mcp/) [![MCP](https://img.shields.io/badge/MCP-Model_Context_Protocol-8A2BE2)](https://modelcontextprotocol.io) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)

**La couche d'intelligence qui rend la donnée publique française *exploitable* par votre agent IA.**

La donnée publique française est ouverte — mais **brute, éparpillée sur des dizaines d'APIs, et illisible en contexte**. Le vrai défi n'est pas d'y *accéder*, c'est de la **comprendre** : quel jeu de données, quelle colonne, quelle interprétation pour *cette* situation précise. C'est là que Nyambot intervient : un **système d'intelligence** qui fait ce travail à la place de votre agent — il interroge, croise, contextualise, et renvoie une **réponse sourcée et directement exploitable, pas des lignes de CSV à parser**.

Votre IA (Claude, ChatGPT, Le Chat…) ne connaît pas la France : seule, elle reformule ce qu'elle a lu, **sans date ni source**. Branchée à Nyambot, elle interroge les données de l'État **à la seconde où vous posez la question** — et cite ses sources.

▶ **L'agent Nyambot complet est en ligne — essayez-le : [nyambot.ai](https://nyambot.ai)**

> Exemple : votre agent enchaîne `resolve_commune` → `risques_immobilier` → `dpe_logement` et **restitue un verdict argumenté** sur un bien en quelques secondes — là où les APIs brutes ne renverraient que des tableaux à interpréter.

- 🧠 **Des réponses, pas des rows.** 1 appel = 1 réponse métier exploitable — sans savoir quel dataset ni quelle colonne interroger.
- 📎 **Sourcé, sans hallucination.** Chaque réponse porte sa source officielle (date, référence, montant).
- 🆓 **Gratuit, sans clé API** pour ce cœur open-source — installation en une ligne via `uvx`.
- 📖 **Open-source, licence MIT.**

> **Ce package = le cœur open-source keyless (4 outils, en local).** Pour la **version complète — 21 outils** (marché immobilier DVF réel, Légifrance, SIRENE, fiches Service-Public, aides…), réponses **answer-ready** et **sourcées** : le connecteur **hébergé** est **en ligne** → **`https://mcp.nyambot.ai/mcp`** (OAuth 2.1). Intégration **backend / serveur-à-serveur** (clés machine) **sur demande**. Détails plus bas.

---

## Pourquoi Nyambot — le game changer

En France, **des milliards d'euros de droits ne sont pas réclamés** chaque année — pas par manque d'éligibilité, mais parce que l'administration est un labyrinthe. Le problème n'a jamais été l'accès à la donnée (elle est publique) : c'est de la **comprendre correctement, en contexte, sans se tromper**. C'est exactement le travail que fait la couche d'intelligence de Nyambot — et c'est ce qu'un accès brut aux APIs ne vous donnera jamais.

[Nyambot.ai](https://nyambot.ai) est un agent IA qui ne se contente pas d'**informer** : il **exécute les démarches**, ancré sur la donnée officielle de l'État, **chaque réponse sourcée, sans hallucination**. Là où un chatbot générique invente et où les portails publics n'accompagnent pas, **Nyambot agit**.

Il couvre **tous les cas de vie** — carte d'identité, impôts, permis de conduire, carte grise, aides & allocations, déménagement, succession, création d'entreprise, **immobilier**… `nyambot-mcp` ouvre une partie de cette capacité à votre propre agent IA.

### L'immobilier, déroulé en direct

Sur l'agent complet ([nyambot.ai](https://nyambot.ai)), une question comme *« Cette maison à Pierrelatte à 286 000 € est-elle bien placée ? »* déclenche une analyse **visible étape par étape** — l'agent va chercher le fichier **DVF**, le **déroule**, et le croise avec les risques et le DPE :

```
📊 DVF — Demandes de valeurs foncières (data.gouv.fr)
   Requête : commune = Pierrelatte (26235) · type = Maison · 2023–2024
   → 38 ventes comparables · médiane du secteur ≈ 2 053 €/m²

⚠️ Géorisques : aléa retrait-gonflement des argiles (moyen)
🏷️ DPE du bien : étiquette A
```

> **Verdict** : à ~2 750 €/m², le bien est ~34 % au-dessus de la médiane locale (source DVF, 38 ventes comparables) — justifiable par le DPE A, mais avec une marge de négociation. Point de vigilance : zone d'aléa argiles à vérifier sur le bâti.

Va chercher la donnée officielle, la déroule, la croise, et **cite ses sources** — en quelques secondes. Aucun chatbot générique ne fait ça.

**La v2 est en ligne.** Le connecteur hébergé `mcp.nyambot.ai/mcp` ouvre l'accès à toute la donnée publique française vivante — démarches administratives, prix de l'immobilier au m² **réel** (DVF), textes de loi (Légifrance), données d'entreprises (SIRENE) — déjà indexée, citable, prête à l'emploi.

> *L'accès programmatique à DVF, au RAG des fiches Service-Public et aux sources sémantiques est **disponible dès maintenant** sur le connecteur hébergé (voir plus bas). Le connecteur gratuit ci-dessous couvre communes, géocodage, risques et DPE — en local, sans clé.*

---

## Outils disponibles

| Outil | Ce qu'il fait | Source officielle |
|---|---|---|
| `resolve_commune` | Nom de commune → code INSEE, département, région, coordonnées, population | geo.api.gouv.fr |
| `geocode_address` | Adresse → coordonnées, code postal, commune, code INSEE | Base Adresse Nationale |
| `risques_immobilier` | Risques naturels & technologiques d'une commune (inondation, argiles, séisme, radon…) | Géorisques |
| `dpe_logement` | DPE des logements existants (étiquette A→G, GES, surface, conso) | ADEME |

---

## En quoi est-ce différent du MCP officiel data.gouv ?

Le [serveur MCP de data.gouv.fr](https://github.com/datagouv/datagouv-mcp) et `nyambot-mcp` ne jouent pas au même niveau — ils sont **complémentaires** :

- **datagouv-mcp** expose le **catalogue open-data** : on cherche des jeux de données, on liste des ressources, on requête du tabulaire brut. C'est un outil d'**exploration / analyste de données**.
- **nyambot-mcp** expose des **réponses métier prêtes à l'emploi** : on pose une question (risques d'une commune, DPE d'un logement…) et on reçoit un résultat exploitable, **sans savoir quel dataset ni quelle colonne**. C'est un outil de **décision**.

| | datagouv-mcp (officiel) | nyambot-mcp |
|---|---|---|
| **Niveau** | Catalogue & datasets bruts | Réponses métier curées |
| **Sources** | data.gouv.fr uniquement | Multi-sources : Géorisques, BAN, geo.api.gouv.fr, ADEME… (API natives, hors catalogue data.gouv) |
| **L'agent doit…** | trouver le dataset, deviner les colonnes, construire la requête | …juste appeler l'outil |
| **Cas d'usage type** | « trouve-moi des datasets sur X » | « ce bien est-il à risque ? quel est son DPE ? » |
| **Fiabilité** | dépend du schéma deviné | pré-câblé : 1 appel = 1 réponse |

> **Vous pouvez brancher les deux.** datagouv-mcp pour explorer n'importe quel dataset ; nyambot-mcp pour des réponses rapides sur les cas de vie à forte valeur (immobilier, droits…). Le connecteur **hébergé** (`mcp.nyambot.ai/mcp`, **en ligne**) ajoute l'**interprétation propriétaire** : RAG des fiches Service-Public, article Légifrance exact, marché DVF réel, réponses entièrement sourcées.

---

## Installation

### Prérequis
[`uv`](https://docs.astral.sh/uv/) installé (recommandé). Sinon, voir « Depuis les sources » plus bas.

### Claude Desktop
Ajoutez ceci à votre `claude_desktop_config.json` :

```json
{
  "mcpServers": {
    "nyambot": {
      "command": "uvx",
      "args": ["nyambot-mcp"]
    }
  }
}
```

Puis **redémarrez Claude Desktop**. `uvx` télécharge et lance le serveur automatiquement — rien d'autre à installer.

### Claude Code
Dans le `.mcp.json` à la racine de votre projet :

```json
{
  "mcpServers": {
    "nyambot": { "command": "uvx", "args": ["nyambot-mcp"] }
  }
}
```

Ou en une commande :

```bash
claude mcp add nyambot -- uvx nyambot-mcp
```

### Cursor / VS Code / Windsurf
Même bloc `mcpServers` que ci-dessus, dans la configuration MCP de votre éditeur.

### Depuis les sources (avant publication PyPI)
```json
{
  "mcpServers": {
    "nyambot": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/GabMJ23/nyambot-mcp", "nyambot-mcp"]
    }
  }
}
```

---

## Exemples de questions

Une fois branché, demandez à votre agent :

- « Quel est le code INSEE de Combs-la-Ville ? »
- « Quels sont les risques naturels à Pierrelatte avant d'acheter ? »
- « Donne-moi des DPE autour du 75011. »
- « J'envisage d'acheter au 8 boulevard du Port à Amiens — géocode l'adresse et liste les risques de la commune. »

**Exemple de réponse réelle** — `risques_immobilier("Pierrelatte")`, via le connecteur gratuit :

```
Risques recensés pour Pierrelatte (INSEE 26235) :
- Effet toxique
- Inondation
- Mouvement de terrain
- Nucléaire
- Risque industriel
- Séisme
- Transport de marchandises dangereuses
```

---

## Vérifier que c'est branché

- Claude Code : `claude mcp list` (statut `connected`) ou `/mcp` dans une session.
- Mode debug pour voir les appels passer : `claude --debug`.

---

## Développement

```bash
git clone https://github.com/GabMJ23/nyambot-mcp
cd nyambot-mcp
uv venv && uv pip install -e ".[dev]"

# Lancer les tests (offline, sans réseau)
pytest

# Lancer le serveur localement
nyambot-mcp
```

---

## Cœur open-source (ce package) vs connecteur hébergé (en ligne)

`nyambot-mcp` est la **partie gratuite et open-source** : un connecteur qui appelle directement les API publiques de l'État, sans clé, **en local** (4 outils : communes, géocodage, risques, DPE).

Le connecteur **hébergé** — **`https://mcp.nyambot.ai/mcp`**, **en ligne** — fédère **21 outils** answer-ready sur l'administration française, y compris ceux qui nécessitent des **sources sémantiques** et de l'**infrastructure hébergée** (non self-hostables) :

- 🏠 **Marché immobilier DVF réel** — médiane €/m² sur transactions réellement actées
- ⚖️ **Légifrance** — l'article de loi exact, texte à jour
- 💼 **SIRENE / INSEE** (vérification d'entreprise), **Annuaire Santé (ANS)**, **France Travail**
- 📚 **RAG des fiches Service-Public** (recherche sémantique)
- ✍️ **Génération de courriers** administratifs, **simulation d'aides**
- …et plus — le tout en réponses **structurées et entièrement sourcées**.

**Comment y accéder :**

- **Usage interactif** (agent piloté par un humain — Claude, ChatGPT, Cursor…) : pointez votre client sur `https://mcp.nyambot.ai/mcp`. Connexion **OAuth 2.1** (PKCE) gérée, elle s'ouvre au 1ᵉʳ appel.
- **Intégration backend / serveur-à-serveur** : **clés machine** (OAuth *client credentials*) **provisionnées sur demande** — on vous fournit un `client_id` + `client_secret`, vous obtenez un token et appelez le connecteur en `Bearer`.

**Sous le capot (la plateforme hébergée) :**

- Construit sur **Claude (Anthropic)**, avec un **routage multi-modèles** (Haiku / Sonnet) selon la tâche.
- **Recherche hybride** (dense + lexicale) sur un corpus souverain (fiches Service-Public, codes en vigueur, catalogue data.gouv).
- Contrat **answer-ready** : 1 appel = 1 réponse sourcée, avec **dégradation honnête** (jamais d'erreur qui casse votre agent).

**Stack technique (plateforme hébergée) :**

`Python 3.12` · `FastAPI` · `MCP SDK` (Streamable HTTP) · `Anthropic SDK` · `PostgreSQL + pgvector` (recherche vectorielle) · embeddings `bge-m3` souverains · **FTS** Postgres (recherche lexicale) · `SSE` (streaming temps réel) · `OAuth 2.1` (PKCE + client credentials) · `Alembic` (migrations) · `Pydantic` · `httpx` · déployé sur **Railway (UE)**.

> Le connecteur open-source de ce dépôt reste volontairement minimal (`Python` + `mcp` + `httpx`) : toute l'infrastructure d'intelligence ci-dessus vit sur la plateforme hébergée.

Le connecteur local restera **open-source et gratuit** ; les capacités hébergées passent par le backend (OAuth / clé machine).

> **Vous voulez brancher le connecteur hébergé ou une clé machine backend ?** Écrivez-moi (voir Contact ci-dessous).

---

## Contact

Questions, retours, demande de clé API v2, ou partenariat :

**Gabriel Mbenda** — AI Builder & Founder, [Nyambot.ai](https://nyambot.ai)
📧 [gabrielmbenda48@gmail.com](mailto:gabrielmbenda48@gmail.com)

---

## Licence

[MIT](./LICENSE) © 2026 Gabriel Mbenda — un projet [Nyambot.ai](https://nyambot.ai).

Les données proviennent des sources officielles du gouvernement français (licence Etalab ouverte). Nyambot est un service indépendant, non affilié à l'État.

---

`mcp-name: io.github.GabMJ23/nyambot-mcp`