Exemplu complet: Server local cu agent
Pe această pagină
Actualizat la 2 noiembrie 2026 — MCP Python SDK v2. Acest curs urmează acum versiunea 2 a SDK-ului
mcp(2.3.0 la data de 2 octombrie 2026):MCPServerînlocuieșteFastMCP, setările de transport se mută înrun()saustreamable_http_app(), iar o aplicație expusă sub un nume de gazdă real trebuie să declare acel nume de gazdă (transport_security). Aceasta este, de asemenea, versiunea cerută de Mistral SDK: extra-ulmistralai[agents]necesitămcp>=2.2.0,<3.0. Surse: Ce este nou în v2 · Ghid de migrare · Deploy & scale. Addendum 3 noiembrie: citiți rezultatul unuirun_asyncdinresult.output_as_text(SDK-ulmistralai3.7.0 nu are atributuloutput), iar în modul de streaming, ultimul eveniment este unRunResult, identificat cuisinstance, ca în exemplul oficial SDK.
Asamblarea componentelor
Lecțiile anterioare au prezentat blocurile de construcție separat: serverul și instrumentele sale, clientul și contextul său RunContext. Acum le veți asambla într-un proiect funcțional—un server MCP local care furnizează informații meteorologice, condus de un agent Mistral capabil să răspundă la întrebări în limbaj natural. Citiți codul, dar acordați o atenție deosebită deciziilor luate de fiecare parte: serverul decide ce este posibil, iar agentul decide ce este relevant.
Serverul: weather_server.py
Acest server constă în trei instrumente. Primul returnează vremea pentru un oraș, al doilea compară două orașe, iar al treilea listează conținutul bazei de date. Ultimul nu este decorativ: oferă modelului o modalitate de a descoperi domeniul de aplicare disponibil, în loc să ghicească nume de orașe.
# weather_server.py
"""Local MCP server providing weather tools."""
from mcp.server.mcpserver import MCPServer
import json
app = MCPServer("Weather Service")
# Simulated database
WEATHER_DATA = {
"paris": {"temp": 18.5, "condition": "Cloudy", "humidity": 72},
"lyon": {"temp": 22.0, "condition": "Sunny", "humidity": 45},
"marseille": {"temp": 25.3, "condition": "Sunny", "humidity": 38},
"lille": {"temp": 14.2, "condition": "Rainy", "humidity": 88},
"bordeaux": {"temp": 20.1, "condition": "Partly cloudy", "humidity": 55},
}
@app.tool()
def get_weather(city: str) -> str:
"""Retrieves current weather for a French city.
Args:
city: City name in lowercase (paris, lyon, marseille, etc.)
Returns:
JSON with temperature, condition, and humidity.
Returns an error if the city is unknown.
"""
city_lower = city.lower().strip()
if city_lower in WEATHER_DATA:
data = WEATHER_DATA[city_lower]
return json.dumps({
"city": city.capitalize(),
"temperature_celsius": data["temp"],
"condition": data["condition"],
"humidity_percent": data["humidity"],
}, ensure_ascii=False)
return json.dumps({"error": f"City {city} not found. Available cities: {', '.join(WEATHER_DATA.keys())}"})
@app.tool()
def compare_weather(city_a: str, city_b: str) -> str:
"""Compares weather between two French cities.
Args:
city_a: First city (lowercase)
city_b: Second city (lowercase)
Returns:
Comparison of temperatures and conditions for both cities
"""
a = WEATHER_DATA.get(city_a.lower().strip())
b = WEATHER_DATA.get(city_b.lower().strip())
if not a:
return f"Unknown city: {city_a}"
if not b:
return f"Unknown city: {city_b}"
diff = a["temp"] - b["temp"]
warmer = city_a if diff > 0 else city_b
return json.dumps({
"city_a": {"name": city_a.capitalize(), **a},
"city_b": {"name": city_b.capitalize(), **b},
"temperature_difference": abs(diff),
"warmer_city": warmer.capitalize(),
}, ensure_ascii=False)
@app.tool()
def list_cities() -> str:
"""Lists all cities available in the weather database.
Returns:
List of cities with their current temperature
"""
cities = [
{"city": k.capitalize(), "temp": v["temp"], "condition": v["condition"]}
for k, v in WEATHER_DATA.items()
]
return json.dumps(cities, ensure_ascii=False)
Două detalii de design merită atenție. Instrumentele normalizează intrarea cu .lower().strip() deoarece modelul ar putea scrie „Paris“ sau „paris“ în funcție de formularea utilizatorului. Iar atunci când un oraș lipsește, get_weather nu aruncă o excepție: returnează un JSON de eroare care enumeră orașele cunoscute, transformând eșecul în informații pe care modelul le poate utiliza.
Clientul: main.py
Clientul face patru lucruri în ordine: inițializează Mistral, creează agentul, descrie modul de lansare a serverului, apoi deschide RunContext pentru a înlănțui conversațiile.
# main.py
"""MCP client with Mistral agent for weather queries."""
import asyncio
import os
from pathlib import Path
from mistralai.client import Mistral
from mistralai.extra.run.context import RunContext
from mistralai.extra.mcp.stdio import MCPClientSTDIO
from mcp import StdioServerParameters
from pydantic import BaseModel
# Configuration
MISTRAL_API_KEY = os.environ.get("MISTRAL_API_KEY")
SERVER_PATH = Path(__file__).parent / "weather_server.py"
# Structured output format (optional)
class WeatherResponse(BaseModel):
summary: str
details: dict | None = None
async def main():
# 1. Initialize Mistral client
client = Mistral(api_key=MISTRAL_API_KEY)
# 2. Create the agent
agent = client.beta.agents.create(
model="mistral-medium-latest",
name="weather-assistant",
instructions=(
"You are a weather assistant for France. "
"Use available tools to answer questions. "
"Always respond in French with metric units."
),
)
# 3. Configure local MCP server
server_params = StdioServerParameters(
command="python",
args=[str(SERVER_PATH)],
env=None,
)
mcp_client = MCPClientSTDIO(stdio_params=server_params)
# 4. Open context and register MCP client
async with RunContext(
agent_id=agent.id,
continue_on_fn_error=True,
) as run_ctx:
await run_ctx.register_mcp_client(mcp_client=mcp_client)
# 5. Launch conversations
questions = [
"What's the weather like in Paris?",
"Compare the weather between Marseille and Lille.",
"Which city is the warmest right now?",
]
for question in questions:
print(f"\n{'='*60}")
print(f"Question: {question}")
print(f"{'='*60}")
result = await client.beta.conversations.run_async(
run_ctx=run_ctx,
inputs=question,
)
print(f"Response: {result.output_as_text}")
# 6. Automatic cleanup upon exiting context manager
print("\nAgent and MCP server closed cleanly.")
if __name__ == "__main__":
asyncio.run(main())
Observați calea serverului: Path(__file__).parent / "weather_server.py" localizează fișierul relativ la script, nu la directorul curent. Aceasta este singura modalitate de a garanta că lansarea funcționează indiferent de unde executați python main.py.
Rularea proiectului
# Set API key
export MISTRAL_API_KEY="your_mistral_api_key"
# Launch client (it will launch the server automatically)
python main.py
Porniți un singur proces. Clientul creează agentul Mistral, RunContext lansează weather_server.py ca proces STDIO, descoperă cele trei instrumente—get_weather, compare_weather și list_cities—apoi, întrebare cu întrebare, permite modelului să aleagă pe care să le apeleze înainte de a integra rezultatele în răspunsul său. A treia întrebare din exemplu este cea mai interesant de observat: pentru a ști care oraș este cel mai cald, modelul nu are de ales decât să treacă prin list_cities, chiar dacă niciun cuvânt din întrebare nu sugerează acest lucru.
Urmărirea construirii răspunsului
Așteptarea răspunsului complet funcționează pentru un script; în fața unui utilizator, modul streaming oferă o experiență mult mai bună.
from mistralai.extra.run.result import RunResult
async with RunContext(agent_id=agent.id) as run_ctx:
await run_ctx.register_mcp_client(mcp_client=mcp_client)
events = await client.beta.conversations.run_stream_async(
run_ctx=run_ctx,
inputs="What's the weather like in Lyon?",
)
async for event in events:
if isinstance(event, RunResult):
# Last event: complete run result
print(event.output_as_text)
else:
# Intermediate events (tool calls, etc.)
print(f"[Event] {event}")
Fluxul de evenimente nu servește doar afișării: este, de asemenea, cel mai bun instrument de depanare, deoarece expune apelurile de instrumente și argumentele alese de model în timp real.
Când un instrument eșuează
Datorită continue_on_fn_error=True, o cerere în afara domeniului de aplicare nu strică nimic. Dacă utilizatorul cere vremea pentru Tokyo, get_weather returnează JSON-ul său de eroare, modelul îl citește și reacționează propunând orașele disponibile efectiv.
# If the user requests a non-existent city:
# → get_weather returns {"error": "City tokyo not found..."}
# → The model reads the error and reformulates its response
# → "I'm sorry, Tokyo is not in my database. Here are the available cities..."
În final, proiectul se încadrează în patru fișiere, dintre care doar două conțin logică:
weather-mcp-project/
├── weather_server.py # MCP server (3 tools)
├── main.py # Client with Mistral agent
├── requirements.txt # mcp>=2.2,<3, mistralai[agents], pydantic
└── .env # MISTRAL_API_KEY=...
Puncte cheie
- Un proiect MCP complet = server (instrumente) + client (agent + RunContext)
- Serverul definește instrumente cu
MCPServerși decoratorii@app.tool() - Clientul creează agentul, deschide RunContext și lansează conversațiile
- Modul Streaming permite afișarea progresivă
continue_on_fn_error=Truegestionează erorile instrumentelor cu grație- Tot codul este asincron—utilizați
asyncio.run()ca punct de intrare