🤖 Server MCP - Agent LangGraph avec outils Math & Météo

🎯 Objectif pédagogique : Ce projet a pour but de montrer comment utiliser le protocole MCP (Model Context Protocol) pour connecter un agent IA à des outils externes, en utilisant les deux types de transport : stdio et streamable_http.

Un projet d'agent IA basé sur LangChain, LangGraph et le protocole MCP (Model Context Protocol), connectant un modèle LLM Groq à des outils externes via des serveurs MCP, avec observabilité via LangSmith et Langfuse.

Qu'est-ce que MCP ?

Le Model Context Protocol est un standard ouvert qui permet à un LLM de communiquer avec des outils externes (serveurs MCP) de manière structurée. Il définit comment un agent peut découvrir, appeler et recevoir les résultats d'outils distants, quel que soit le langage ou la plateforme utilisée.

Ce projet illustre deux modes de communication MCP :

Transport	Cas d'usage	Exemple dans ce projet
stdio	Outil local, lancé par le client	mathserver.py
streamable_http	Outil distant, serveur indépendant	weather.py

---

📁 Structure du projet

Server_mcp/
├── src/
│   ├── client.py          # Agent principal (LangGraph + Groq)
│   ├── mathserver.py      # Serveur MCP — outils mathématiques (stdio)
│   └── weather.py         # Serveur MCP — outil météo (streamable_http)
├── .env                   # Clés API (non versionné)
├── .env.example           # Modèle de variables d'environnement
├── .gitignore
├── .python-version        
├── .venv/                
├── pyproject.toml         # Configuration du projet
├── requitements.txt      
├── uv.lock               
└── README.md

---

⚙️ Prérequis

• Python 3.11+ (voir .python-version)
• uv — gestionnaire de paquets (recommandé)
• Un compte Groq pour la clé API LLM
• Un compte LangSmith pour le tracing
• Un compte Langfuse pour l'observabilité

---

🚀 Installation

Avec uv (recommandé)

cd Server_mcp
uv sync

Avec pip classique

cd Server_mcp
python -m venv .venv
source .venv/bin/activate  # Sur Windows : .venv\Scripts\activate
pip install -r requitements.txt

Configurer les variables d'environnement

Copier le fichier .env.example et remplir les valeurs :

cp .env.example .env

Contenu du .env :

# LLM
GROQ_API_KEY=votre_clé_groq_ici

# LangSmith (tracing & évaluation)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=votre_clé_langsmith_ici
LANGCHAIN_PROJECT=server_mcp

# Langfuse (observabilité & analytics)
LANGFUSE_PUBLIC_KEY=votre_clé_publique_langfuse_ici
LANGFUSE_SECRET_KEY=votre_clé_secrète_langfuse_ici
LANGFUSE_HOST=https://cloud.langfuse.com

---

🧩 Architecture

Ce projet utilise deux types de transport MCP :

Fichier	Transport	Lancement
src/mathserver.py	stdio	Automatique via le client
src/weather.py	streamable_http	Manuel sur le port 8000

src/client.py
    ├── MultiServerMCPClient
    │       ├── math (stdio)    → src/mathserver.py
    │       └── weather (http)  → src/weather.py :8000
    ├── ChatGroq (openai/gpt-oss-120b)
    ├── create_agent (LangChain)
    ├── LangSmith  ──────────────────────→ smith.langchain.com
    └── Langfuse   ──────────────────────→ cloud.langfuse.com

---

📊 Observabilité

LangSmith

Trace automatiquement toutes les invocations de l'agent, les appels aux outils MCP et les réponses du modèle. Accessible sur smith.langchain.com sous le projet server_mcp.

Langfuse

Fournit des analytics détaillés sur les coûts, latences et qualité des réponses LLM. Accessible sur cloud.langfuse.com.

---

🛠️ Les outils disponibles

Serveur Math (src/mathserver.py)

Outil	Description	Paramètres
add	Additionne deux nombres	a: float, b: float
subtract	Soustrait deux nombres	a: float, b: float

Serveur Météo (src/weather.py)

Outil	Description	Paramètres
get_weather	Retourne la météo d'une ville	location: str

---

▶️ Lancer le projet

Étape 1 — Démarrer le serveur météo (Terminal 1)

source .venv/bin/activate
python src/weather.py

Le serveur démarre sur http://127.0.0.1:8000/mcp

Étape 2 — Lancer le client agent (Terminal 2)

source .venv/bin/activate
python src/client.py

Résultat attendu

Les outils disponibles: ['add', 'subtract', 'get_weather']
La réponse à votre question: (4+5) = 9 et (54-50) = 4

---

🐛 Erreurs fréquentes

Erreur	Cause	Solution
Missing 'transport' key	Clé transport absente dans la config	Ajouter "transport": "stdio" ou "streamable_http"
SyntaxError: forgot a comma	print("texte" variable)	Ajouter une virgule : print("texte", variable)
object dict can't be used in await	Utilisation de .invoke() au lieu de .ainvoke()	Remplacer par await agent.ainvoke(...)
streamable-http non reconnu	Tiret au lieu d'underscore	Utiliser streamable_http
Push GitHub bloqué	Fichier .env commité avec des clés	Révoquer les clés, retirer .env de l'historique Git

---

📚 Technologies utilisées

• LangChain - Framework LLM
• LangGraph - Agent ReAct
• langchain-mcp-adapters -Intégration MCP
• FastMCP - Création de serveurs MCP
• Groq — Inférence LLM ultra-rapide
• LangSmith - Tracing & évaluation des chaînes LLM
• Langfuse - Observabilité & analytics LLM
• uv - Gestionnaire de paquets moderne
• python-dotenv- Gestion des variables d'environnement

---

👤 Auteur

BANE Seydina Mouhamet