MCP 服务器

Server MCP

Provides math and weather tools accessible via LangGraph agent using MCP protocol with stdio and streamable HTTP transports.

README

🤖 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