Teljes példa: Helyi szerver ágenssel
Ezen az oldalon
Frissítve: 2026. november 2. — MCP Python SDK v2. Ez a tanfolyam az
mcpSDK 2-es verzióját követi (2026. október 2-i állapot szerint 2.3.0): azMCPServerleváltja aFastMCP-et, a transzportbeállítások arun()vagystreamable_http_app()függvényekbe kerültek, és egy valódi hosztnéven elérhető alkalmazásnak deklarálnia kell ezt a hosztnevet (transport_security). Ez az a verzió, amelyet a Mistral SDK is megkövetel: amistralai[agents]extra függőséghezmcp>=2.2.0,<3.0szükséges. Források: Újdonságok a v2-ben · Migrációs útmutató · Telepítés és skálázás. Kiegészítés november 3.: arun_asynceredményét aresult.output_as_textattribútumból olvasd ki (amistralaiSDK 3.7.0 verziójában nincsoutputattribútum), streaming módban pedig az utolsó esemény egyRunResult, amelyet azisinstancefüggvénnyel azonosítasz, ahogy azt a hivatalos SDK példa is mutatja.
Az elemek összeillesztése
Az előző leckék külön-külön mutatták be az építőköveket: a szervert és annak eszközeit, valamint a klienst és annak RunContextjét. Most ezeket egy működő projektté állítod össze: egy helyi MCP szerverré, amely időjárási információkat szolgáltat, és egy Mistral ágens vezérli, képes természetes nyelven válaszolni a kérdésekre. Olvasd át a kódot, de fordíts különös figyelmet arra, hogy melyik rész mit dönt el: a szerver határozza meg, mi lehetséges, az ágens pedig azt, mi releváns.
A szerver: weather_server.py
Ez a szerver három eszközből áll. Az első egy város időjárását adja vissza, a második összehasonlít két várost, a harmadik pedig felsorolja, mit tartalmaz az adatbázis. Ez utóbbi nem csak dísz: lehetőséget ad a modellnek, hogy felfedezze a rendelkezésre álló kört városnevek találgatása helyett.
# 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)
Két tervezési részlet érdemel figyelmet. Az eszközök a .lower().strip() metódussal normalizálják a bemenetet, mert a modell írhatja úgy is, hogy „Paris“, úgy is, hogy „paris“, a felhasználó megfogalmazásától függően. Amikor pedig egy város hiányzik, a get_weather nem dob kivételt: helyette egy hibát jelző JSON-t ad vissza, amely felsorolja az ismert városokat, így a kudarcot olyan információvá alakítja, amelyet a modell fel tud használni.
A kliens: main.py
A kliens négy dolgot hajt végre sorrendben: inicializálja a Mistralt, létrehozza az agenst, leírja, hogyan indítsa el a szervert, majd megnyitja a RunContextet a beszélgetések láncolásához.
# 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())
Figyeld meg a szerver elérési útját: a Path(__file__).parent / "weather_server.py" a fájlt a szkripthez képest lokalizálja, nem pedig az aktuális munkakönyvtárhoz. Csak így garantálható, hogy a indítás működik, függetlenül attól, honnan futtatod a python main.py parancsot.
A projekt futtatása
# Set API key
export MISTRAL_API_KEY="your_mistral_api_key"
# Launch client (it will launch the server automatically)
python main.py
Csak egyetlen folyamatot indítasz el. A kliens létrehozza a Mistral agenst, a RunContext elindítja a weather_server.py fájlt STDIO folyamatként, felfedezi a három eszközt – get_weather, compare_weather és list_cities –, majd kérdésről kérdésre lehetővé teszi a modell számára, hogy kiválassza, melyiket hívja meg, mielőtt az eredményeket integrálná a válaszába. A példában a harmadik kérdés a legérdekesebb megfigyelni: ahhoz, hogy megtudja, melyik város a legmelegebb, a modellnek nincs más választása, mint végigmenni a list_cities eszközön, még akkor is, ha a kérdésben egyetlen szó sem utal erre.
A válasz felépülésének figyelése
A teljes válaszra való várakozás működik egy szkript esetén; felhasználóval szemben azonban a streaming mód sokkal jobb élményt nyújt.
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}")
Az eseményfolyam nem csupán megjelenítésre szolgál: ez a legjobb hibakereső eszközöd is, mivel valós időben tárja fel a modell által választott eszközlehívásokat és argumentumokat.
Amikor egy eszköz meghibásodik
A continue_on_fn_error=True beállításnak köszönhetően egy hatókörön kívüli kérés nem okoz összeomlást. Ha a felhasználó Tokió időjárását kérdezi, a get_weather visszaadja a hibát jelző JSON-t, a modell elolvassa azt, és úgy reagál, hogy felajánlja a ténylegesen elérhető városokat.
# 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..."
Végül a projekt négy fájlból áll, amelyek közül csak kettő tartalmaz logikát:
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=...
Főbb megállapítások
- Egy teljes MCP projekt = szerver (eszközök) + kliens (ágens + RunContext)
- A szerver az
MCPServerosztállyal és az@app.tool()dekorátorokkal definiálja az eszközöket - A kliens létrehozza az agenst, megnyitja a RunContextet, és elindítja a beszélgetéseket
- A streaming mód lehetővé teszi a fokozatos megjelenítést
- A
continue_on_fn_error=Truegracefully kezeli az eszközhibákat - Minden kód aszinkron – használd az
asyncio.run()függvényt belépési pontként