Kompletný príklad: Lokálny server s agentom
Na tejto strane
Aktualizované 2. novembra 2026 — MCP Python SDK v2. Tento kurz teraz nasleduje verziu 2 SDK
mcp(2.3.0 k 2. októbru 2026):MCPServernahrádzaFastMCP, nastavenia transportu sa presúvajú dorun()alebostreamable_http_app()a aplikácia vystavená pod skutočným hostname musí tento hostname deklarovať (transport_security). Toto je tiež verzia požadovaná Mistral SDK: extra balíkmistralai[agents]vyžadujemcp>=2.2.0,<3.0. Zdroje: Čo je nové vo v2 · Sprievodca migráciou · Nasadenie a škálovanie. Dodatok 3. novembra: výsledokrun_asyncčítaj zresult.output_as_text(SDKmistralai3.7.0 nemá atribútoutput) a v režime streamovania je poslednou udalosťouRunResult, identifikovateľný pomocouisinstance, ako v oficiálnom príklade SDK.
Spájanie dielov dohromady
Predchádzajúce lekcie položili stavebné kamene oddelene: server s jeho nástrojmi, klient a jeho RunContext. Teraz ich spojíš do funkčného projektu – lokálneho MCP servera poskytujúceho informácie o počasí, poháňaného agentom Mistral schopným odpovedať na otázky v prirodzenom jazyku. Čítaj kód, ale venuj pozornosť tomu, čo rozhoduje každá časť: server rozhoduje o tom, čo je možné, agent rozhoduje o tom, čo je relevantné.
Server: weather_server.py
Tento server pozostáva z troch nástrojov. Prvý vracia počasie pre mesto, druhý porovnáva dve mestá a tretí vypisuje obsah databázy. Ten posledný nie je len ozdobný: dáva modelu spôsob, ako objaviť dostupný rozsah namiesto hádania názvov miest.
# 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)
Dva detaily dizajnu si zaslúžia pozornosť. Nástroje normalizujú vstup pomocou .lower().strip(), pretože model môže napísať „Paris“ alebo „paris“ v závislosti od formulácie používateľa. A keď mesto chýba, get_weather nevyhodí výnimku: vráti JSON s chybou, ktorý vymenúva známe mestá, čím mení zlyhanie na informáciu, ktorú môže model využiť.
Klient: main.py
Klient robí štyri veci v poradí: inicializuje Mistral, vytvorí agenta, popíše, ako spustiť server, a potom otvorí RunContext na reťazenie konverzácií.
# 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())
Všimni si cestu k serveru: Path(__file__).parent / "weather_server.py" lokalizuje súbor relatívne k skriptu, nie k aktuálnemu adresáru. Toto je jediný spôsob, ako zaručiť, že spustenie bude fungovať bez ohľadu na to, odkiaľ spustíš python main.py.
Spustenie projektu
# Set API key
export MISTRAL_API_KEY="your_mistral_api_key"
# Launch client (it will launch the server automatically)
python main.py
Spustíš iba jeden proces. Klient vytvorí agenta Mistral, RunContext spustí weather_server.py ako proces STDIO, objaví tri nástroje – get_weather, compare_weather a list_cities – a potom, otázku po otázke, nechá model vybrať, ktoré z nich zavolať, predtým než integruje výsledky do svojej odpovede. Tretia otázka v príklade je najzaujímavejšia na pozorovanie: aby vedel, ktoré mesto je najteplejšie, model nemá na výber a musí prejsť cez list_cities, hoci žiadne slovo v otázke to nenaznačuje.
Sledovanie budovania odpovede
Čakanie na úplnú odpoveď funguje pre skript; pri práci s používateľom však režim streamovania ponúka oveľa lepší zážitok.
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}")
Stream udalostí nie je len na zobrazenie: je to aj tvoj najlepší nástroj na ladenie, pretože v reálnom čase odhaľuje volania nástrojov a argumenty vybrané modelom.
Keď nástroj zlyhá
Vďaka continue_on_fn_error=True požiadavka mimo rozsahu nič nerozbije. Ak používateľ požiada o počasie v Tokiu, get_weather vráti svoj JSON s chybou, model si ho prečíta a reaguje návrhom skutočne dostupných miest.
# 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..."
Nakoniec, projekt sa zmestí do štyroch súborov, z ktorých iba dva obsahujú logiku:
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=...
Kľúčové poznatky
- Kompletný projekt MCP = server (nástroje) + klient (agent + RunContext)
- Server definuje nástroje pomocou
MCPServera dekorátorov@app.tool() - Klient vytvára agenta, otvára RunContext a spúšťa konverzácie
- Režim streamovania umožňuje postupné zobrazovanie
continue_on_fn_error=Trueelegantne rieši chyby nástrojov- Všetok kód je asynchrónny – ako vstupný bod používaj
asyncio.run()