Skip to content

dev.md

Latest commit

 

History

History
206 lines (144 loc) · 6.32 KB

dev.md

File metadata and controls

206 lines (144 loc) · 6.32 KB

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 :

nvm install
nvm use

Installation

# 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/

npm run build

Démarrer le serveur MCP

La commande suivante démarre le serveur MCP en mode "stdio" :

node --use-env-proxy dist/index.js

Avec certains clients MCP, vous serez amené à éditer un fichier JSON. Par exemple :

{
  "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. - Voir configuration du serveur MCP 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.

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

npm run test:unit
# ou simplement
npm test

Tests d'intégration (niveau 1)

npm run build
npm run test:integration

Tests E2E agent (niveau 2)

npm run build
npm run test:e2e

Couverture

npm run test:coverage

Vérifications combinées

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 :

export MODEL_NAME=anthropic:claude-haiku-4-5
export ANTHROPIC_API_KEY=...
npm run build
npm run test:e2e

Avec Ollama en local :

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 est recommandée pour gérer les monter de version :

# é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 :

npm run docs:mcp