review readme to make it more readable

docs/config.md

@@ -0,0 +1,26 @@
+# Configuration du serveur MCP
+
+## Points clés
+
+- L'utilisation du MCP sous forme d'un processus local (`npx -y @ignfab/geocontext`) ne requiert pas de paramétrage.
+- **Cette section concerne les développeurs du MCP et les utilisateurs avancés du MCP** (démarrer localement la version HTTP, configurer les logs,...)
+
+## Principaux paramètres
+
+| Nom                          | Description                                                                                                                                                                                                                                                                                       | Valeur par défaut                                |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `TRANSPORT_TYPE`             | [Transport](https://mcp-framework.com/docs/Transports/transports-overview) permet de choisir entre "stdio" et "http"                                                                                                                                                                              | "stdio" (version locale) / "http" (docker)       |
+| `HTTP_HOST`                  | Adresse d'écoute en mode HTTP. Utile avec Docker pour exposer le service via `0.0.0.0`.                                                                                                                                                                                                           | "127.0.0.1"                                      |
+| `HTTP_PORT`                  | Port d'écoute du MCP                                                                                                                                                                                                                                                                              | 3000                                             |
+| `HTTP_MCP_ENDPOINT`          | Chemin d'exposition du MCP en HTTP                                                                                                                                                                                                                                                                | "/mcp"                                           |
+| `HTTP_CORS_ALLOWED_ORIGINS`  | Permet la [configuration de allowedOrigins pour protection contre les attaques par DNS rebinding](https://www.mcp-framework.com/docs/transports/http-stream#origin-validation-dns-rebinding-protection). Exemple : `HTTP_CORS_ALLOWED_ORIGINS="http://localhost:3000,https://geollm.beta.ign.fr"` | Aucun (warning)                                  |
+| `HTTP_TIMEOUT`               | Délai maximal, en secondes, pour les appels HTTP sortants vers les services amont IGN. Au-delà, la requête est interrompue et l'outil renvoie une erreur de timeout structurée.                                                                                                                   | `15`                                             |
+| `GPF_WFS_RATE_LIMIT`         | Nombre maximum de requêtes par seconde sur le WFS de la Géoplateforme.                                                                                                                                                                                                                            | 30                                               |
+| `GPF_WFS_MINISEARCH_OPTIONS` | Chaîne JSON optionnelle permettant de configurer `gpf_wfs_search_types`.                                                                                                                                                                                                                          | options par défaut de `@ignfab/gpf-schema-store` |
+| `LOG_FORMAT`                 | Le format d'écriture des logs : "json" ou "simple".                                                                                                                                                                                                                                               | "simple"                                         |
+| `LOG_LEVEL`                  | Le niveau d'écriture des logs : ["error", "info", ou "debug"](https://github.com/winstonjs/winston#logging-levels)                                                                                                                                                                                | "debug"                                          |
+
+## Paramétrages avancés
+
+- [Configuration d'un proxy d'entreprise](config/proxy.md)
+- [Configurer le moteur de recherche](config/minisearch.md)

docs/config/minisearch.md

@@ -0,0 +1,19 @@
+# Configuration avancée de MiniSearch pour la recherche des types
+
+## Contexte
+
+La recherche des tables disponibles ( `gpf_wfs_search_types` ) s'appuie sur le moteur de recherche MiniSearch qui est intégré au dépôt [ignfab/gpf-schema-store](https://github.com/ignfab/gpf-schema-store#readme).
+
+**Cette documentation est à destination des développeurs** souhaitant tester des modifications sur les poids.
+
+## Configuration de la recherche
+
+Si `GPF_WFS_MINISEARCH_OPTIONS` est absent ou vide, les options par défaut `@ignfab/gpf-schema-store` sont utilisées (poids et le comportement par défaut `OR` de MiniSearch pour `combineWith`).
+
+Il est possible de configurer cette variable d'environnement comme suit pour modifier les comportements :
+
+```bash
+export GPF_WFS_MINISEARCH_OPTIONS='{"fields":["title","identifierTokens"],"combineWith":"OR","fuzzy":0.05,"boost":{"title":4,"name":5}}'
+export HTTP_TIMEOUT=15
+```
+

docs/config/proxy.md

@@ -0,0 +1,23 @@
+# Configuration avancée du proxy réseau
+
+## Contexte
+
+Le projet `geocontext` s'appuie sur la gestion native du proxy par Node.js pour les appels HTTP sortants.
+
+**Cette documentation est à destination des développeurs et des utilisateurs de la version locale du MCP** travaillant derrière un proxy d'entreprise.
+
+## Configuration du proxy
+
+Le support du proxy est activé par l'environnement dans les principaux contextes d'exécution :
+
+- En exécution locale, le serveur démarre avec `node --use-env-proxy`.
+- Les tests d'intégration propagent `NODE_USE_ENV_PROXY=1` au sous-processus MCP lancé en `stdio`.
+- Les tests E2E démarrent les workers Vitest avec `--use-env-proxy`.
+
+Il suffit ensuite de définir les variables d'environnement standard selon votre contexte réseau :
+
+```bash
+export HTTP_PROXY=http://proxy.example:3128
+export HTTPS_PROXY=http://proxy.example:3128
+export NO_PROXY=localhost,127.0.0.1
+```

docs/dev.md

@@ -0,0 +1,206 @@
+# Guide développeur
+
+## Pré-requis
+
+- Node.js (voir `package.json` pour la version recommandée)
+- npm compatible avec la version de Node utilisée
+
+Remarque : Le dépôt fournit `.nvmrc` et `.node-version`. Si vous utilisez `nvm`, vous pouvez donc faire :
+
+```bash
+nvm install
+nvm use
+```
+
+</details>
+
+
+## Installation
+
+```bash
+# clonage du dépôt
+git clone https://github.com/ignfab/geocontext
+cd geocontext
+
+# téléchargement des dépendances
+npm ci
+```
+
+## Construction
+
+!!!tip
+    La commande ci-après doit être relancé après chaque modification du code pour **reconstruction du `dist/`**
+
+```bash
+npm run build
+```
+
+## Démarrer le serveur MCP
+
+La commande suivante démarre le serveur MCP en mode "stdio" :
+
+```bash
+node --use-env-proxy dist/index.js
+```
+
+Avec certains clients MCP, vous serez amené à éditer un fichier JSON. Par exemple :
+
+```json
+{
+  "mcpServers": {
+    "geocontext": {
+      "command": "node",
+      "args": ["--use-env-proxy", "/chemin/absolu/vers/geocontext/dist/index.js"]
+    }
+  }
+}
+```
+
+!!!tip
+    - L'option `--use-env-proxy` est facultative. Voir la [configuration du proxy réseau](./config/proxy.md).
+    - Voir [configuration du serveur MCP](./config.md) pour les paramètres disponibles
+
+
+## Déboguer avec MCP Inspector
+
+**MCP Inspector** est l'outil de développement officiel pour tester et déboguer un serveur MCP local.
+
+```bash
+npm run inspect:mcp       # interface graphique
+npm run inspect:mcp:cli   # mode CLI
+```
+
+## Tests
+
+Le projet distingue trois niveaux de tests :
+
+- **Unitaires** : pas de réseau, exécutés par défaut.
+- **Intégration niveau 1** (`test/integration/level1-protocol`) : appels MCP directs vers les tools, avec de vrais appels réseau vers la Géoplateforme.
+- **E2E niveau 2** (`test/integration/level2-agent`) : un agent LangChain branché au serveur MCP local avec un vrai modèle LLM.
+
+Les niveaux 1 et 2 nécessitent un build à jour (`npm run build`) et un accès réseau aux services appelés. Les deux suites s'exécutent séquentiellement pour limiter la charge sur les services externes et éviter de démarrer plusieurs serveurs MCP en parallèle.
+
+### Vue d'ensemble des commandes
+
+| Commande                    | Rôle                                                            |
+| --------------------------- | --------------------------------------------------------------- |
+| `npm run typecheck`         | Type-check de l'application (`tsconfig.json`)                   |
+| `npm run typecheck:test`    | Type-check des fichiers de test (`tsconfig.test.json`)          |
+| `npm test` / `test:unit`    | Tests unitaires                                                 |
+| `npm run test:integration`  | Tests d'intégration niveau 1                                    |
+| `npm run test:e2e`          | Tests E2E agent niveau 2                                        |
+| `npm run test:coverage`     | Tests unitaires avec couverture                                 |
+| `npm run verify:fast`       | `typecheck` + `typecheck:test` + `build` + `test:unit`          |
+| `npm run verify`            | `verify:fast` + `test:integration`                              |
+| `npm run verify:full`       | `verify` + `test:e2e`                                           |
+
+### Tests unitaires
+
+```bash
+npm run test:unit
+# ou simplement
+npm test
+```
+
+### Tests d'intégration (niveau 1)
+
+```bash
+npm run build
+npm run test:integration
+```
+
+### Tests E2E agent (niveau 2)
+
+```bash
+npm run build
+npm run test:e2e
+```
+
+### Couverture
+
+```bash
+npm run test:coverage
+```
+
+### Vérifications combinées
+
+```bash
+npm run verify:fast   # typecheck + build + tests unitaires
+npm run verify        # verify:fast + tests d'intégration niveau 1
+npm run verify:full   # verify + tests E2E niveau 2
+```
+
+### Variables d'environnement
+
+Communes aux suites d'intégration (niveaux 1 et 2) :
+
+| Variable                                  | Description                                                         |
+| ----------------------------------------- | ------------------------------------------------------------------- |
+| `GEOCONTEXT_SERVER_PATH`                  | Chemin vers le point d'entrée du serveur (défaut : `dist/index.js`) |
+| `GEOCONTEXT_LOG_LEVEL`                    | Niveau de log du serveur lancé par les tests                        |
+| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | Configuration proxy réseau                                          |
+
+Spécifiques aux tests E2E agent (`test:e2e`) :
+
+| Variable            | Description                                                         |
+| ------------------- | ------------------------------------------------------------------- |
+| `MODEL_NAME`        | Modèle LangChain à utiliser (défaut : `anthropic:claude-haiku-4-5`) |
+| `ANTHROPIC_API_KEY` | Clé API Anthropic                                                   |
+| `OPENAI_API_KEY`    | Clé API OpenAI                                                      |
+| `GOOGLE_API_KEY`    | Clé API Google                                                      |
+| `MISTRAL_API_KEY`   | Clé API Mistral                                                     |
+
+La clé API requise dépend du provider indiqué dans `MODEL_NAME`.
+
+### Exemples de lancement des tests E2E
+
+Avec Anthropic :
+
+```bash
+export MODEL_NAME=anthropic:claude-haiku-4-5
+export ANTHROPIC_API_KEY=...
+npm run build
+npm run test:e2e
+```
+
+Avec Ollama en local :
+
+```bash
+export MODEL_NAME=ollama:llama3.1
+export OLLAMA_BASE_URL=http://127.0.0.1:11434
+npm run build
+npm run test:e2e
+```
+
+## Dépannage
+
+- Si `test:integration` échoue immédiatement : vérifier que `dist/index.js` existe (`npm run build`).
+- Si `test:e2e` est ignoré : vérifier que la clé API attendue par `MODEL_NAME` est définie.
+- Si un provider local (Ollama, etc.) est utilisé derrière un proxy : ajouter `NO_PROXY=localhost,127.0.0.1`.
+
+## Commandes utiles
+
+### Mettre à jour des dépendances
+
+!!!warning
+    **zod doit rester en version 3**
+
+L'utilisation de [npm-check-updates](https://www.npmjs.com/package/npm-check-updates?activeTab=readme) est recommandée pour gérer les monter de version :
+
+```bash
+# étudier les nouvelles versions disponible
+npx -y npm-check-updates
+
+# mettre à jour les versions mineurs
+npx -y npm-check-updates -t minor -u
+```
+
+
+### Générer la documentation des tools MCP
+
+Pour mettre à jour `docs/mcp-tools.md` à partir des métadonnées des tools :
+
+```bash
+npm run docs:mcp
+```
+