Kompletní příklad: Lokální server s agentem
Na této stránce
Aktualizováno 2. listopadu 2026 — MCP Python SDK v2. Tento kurz nyní vychází z verze 2 SDK
mcp(k 2. říjnu 2026 je to verze 2.3.0):MCPServernahrazujeFastMCP, nastavení transportu se přesouvá dorun()nebostreamable_http_app()a aplikace vystavená pod skutečným hostname musí tento hostname deklarovat (transport_security). Toto je také verze požadovaná Mistral SDK: extra balíčekmistralai[agents]vyžadujemcp>=2.2.0,<3.0. Zdroje: Co je nového ve v2 · Průvodce migrací · Nasazení a škálování. Dodatek ze 3. listopadu: výsledekrun_asyncčti zresult.output_as_text(SDKmistralai3.7.0 nemá atributoutput) a ve streamovacím režimu je poslední událost typuRunResult, což rozpoznáš pomocíisinstance, stejně jako v oficiálním příkladu SDK.
Složení dílů dohromady
Předchozí lekce ti představily stavební kameny odděleně: server s jeho nástroji a klienta s jeho kontextem RunContext. Nyní je spojíš do funkčního projektu – lokálního MCP serveru poskytujícího informace o počasí, řízeného agentem Mistral schopným odpovídat na otázky v přirozeném jazyce. Čti kód pozorně, ale zaměř se hlavně na to, co která část rozhoduje: server určuje, co je možné, agent rozhoduje, co je relevantní.
Server: weather_server.py
Tento server se skládá ze tří nástrojů. První vrací počasí pro dané město, druhý porovnává dvě města a třetí vypisuje obsah databáze. Ten poslední není jen ozdobou: dává modelu možnost objevit dostupný rozsah místo toho, aby hádal názvy měst.
# 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 návrhu si zaslouží pozornost. Nástroje normalizují vstup pomocí .lower().strip(), protože model může napsat „Paris“ nebo „paris“ v závislosti na formulaci uživatele. A když město chybí, get_weather nezvedá výjimku: vrací JSON s chybou, který vyjmenovává známá města, čímž mění selhání v informaci, kterou model může využít.
Klient: main.py
Klient dělá čtyři věci v pořadí: inicializuje Mistral, vytvoří agenta, popíše, jak spustit server, a poté otevře RunContext pro řetězení konverzací.
# 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 cesty k serveru: Path(__file__).parent / "weather_server.py" lokalizuje soubor relativně ke skriptu, nikoliv k aktuálnímu adresáři. To je jediný způsob, jak zaručit, že spuštění funguje bez ohledu na to, odkud spustíš python main.py.
Spuštění projektu
# Set API key
export MISTRAL_API_KEY="your_mistral_api_key"
# Launch client (it will launch the server automatically)
python main.py
Spustíš pouze jeden proces. Klient vytvoří agenta Mistral, RunContext spustí weather_server.py jako proces STDIO, objeví tři nástroje – get_weather, compare_weather a list_cities – a poté otázku po otázce nechá model vybrat, které nástroje zavolat, než výsledky integruje do své odpovědi. Třetí otázka v příkladu je nejzajímavější na pozorování: aby model věděl, které město je nejteplejší, nemá na výběr a musí projít přes list_cities, i když žádné slovo v otázce toto nenaznačuje.
Sledování tvorby odpovědi
Čekání na úplnou odpověď funguje pro skript; při práci s uživatelem nabízí režim streamování mnohem lepší zážitek.
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}")
Proud událostí není jen pro zobrazení: je to také tvůj nejlepší nástroj pro ladění, protože v reálném čase odhaluje volání nástrojů a argumenty vybrané modelem.
Když nástroj selže
Díky continue_on_fn_error=True požadavek mimo rozsah nic nerozbije. Pokud se uživatel zeptá na počasí v Tokiu, get_weather vrátí svůj JSON s chybou, model si ho přečte a reaguje návrhem skutečně dostupných měst.
# 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..."
Nakonec se celý projekt vejde do čtyř souborů, z nichž pouze 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=...
Klíčové poznatky
- Kompletní projekt MCP = server (nástroje) + klient (agent + RunContext)
- Server definuje nástroje pomocí
MCPServera dekorátorů@app.tool() - Klient vytvoří agenta, otevře RunContext a spustí konverzace
- Režim streamování umožňuje postupné zobrazování
continue_on_fn_error=Trueelegantně zpracovává chyby nástrojů- Veškerý kód je asynchronní – jako vstupní bod použij
asyncio.run()