Pavyzdys: vietinis serveris su agentu
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 2 d. — MCP Python SDK v2. Šis kursas dabar remiasi 2 versija (
mcpSDK 2.3.0, 2026 m. spalio 2 d. duomenimis):MCPServerpakeičiaFastMCP, transporto nustatymai perkeliami įrun()arbastreamable_http_app(), o programa, eksponuojama tikruoju prieglobos vardu, privalo jį deklaruoti (transport_security). Tai taip pat yra versija, kurios reikalauja Mistral SDK:mistralai[agents]papildinys reikalaujamcp>=2.2.0,<3.0. Šaltiniai: Kas naujo v2 · Migracijos gidas · Diegimas ir mastelio keitimas. Priedas lapkričio 3 d.:run_asyncrezultatą skaitykite išresult.output_as_text(Mistral SDK 3.7.0 versijoje nėraoutputatributo), o srautiniu režimu paskutinis įvykis yraRunResult, identifikuojamas naudojantisinstance, kaip oficialiame SDK pavyzdyje.
Detalių surinkimas
Ankstesnėse pamokose statybiniai blokai buvo nagrinėjami atskirai: serveris su savo įrankiais, klientas su savo RunContext. Dabar tu juos surinksi į veikiantį projektą – vietinį MCP serverį, teikiantį oro sąlygų informaciją, valdomą Mistral agento, gebančio atsakyti į klausimus natūralia kalba. Skaityk kodą, tačiau atidžiai stebėk, ką kiekviena dalis nusprendžia: serveris nusprendžia, kas yra įmanoma, o agentas – kas yra aktualu.
Serveris: weather_server.py
Šį serverį sudaro trys įrankiai. Pirmasis grąžina oro sąlygas konkrečiam miestui, antrasis lygina du miestus, o trečiasis išvardija, ką turi duomenų bazė. Paskutinysis nėra tik dekoracija: jis suteikia modeliui būdą atrasti turimą aprėptį vietoj to, kad spėtų miestų pavadinimus.
# 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)
Du projektavimo aspektai nusipelno dėmesio. Įrankiai normalizuoja įvestį naudodami .lower().strip(), nes modelis gali parašyti „Paris“ arba „paris“ priklausomai nuo naudotojo formuluotės. Be to, kai miesto nėra, get_weather neišmeta išimties: jis grąžina klaidos JSON, kuriame išvardijami žinomi miestai, taip paversdamas nesėkmę informacija, kurią modelis gali panaudoti.
Klientas: main.py
Klientas atlieka keturis veiksmus iš eilės: inicializuoja Mistral, sukuria agentą, aprašo, kaip paleisti serverį, tada atidaro RunContext pokalbių grandinei sudaryti.
# 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())
Atkreipk dėmesį į serverio kelią: Path(__file__).parent / "weather_server.py" lokalizuoja failą skripto atžvilgiu, o ne esamo katalogo atžvilgiu. Tai vienintelis būdas užtikrinti, kad paleidimas veiktų nepriklausomai nuo to, iš kurio katalogo vykdytum python main.py.
Projekto paleidimas
# Set API key
export MISTRAL_API_KEY="your_mistral_api_key"
# Launch client (it will launch the server automatically)
python main.py
Tu paleidi tik vieną procesą. Klientas sukuria Mistral agentą, RunContext paleidžia weather_server.py kaip STDIO procesą, atranda tris įrankius – get_weather, compare_weather ir list_cities – tada, klausimas po klausimo, leidžia modeliui pasirinkti, kuriuos iš jų iškviesti prieš integruojant rezultatus į savo atsakymą. Trečiasis pavyzdžio klausimas yra įdomiausias stebėjimui: norėdamas sužinoti, kuris miestas yra šilčiausias, modelis neturi kitos išeities, kaip tik naudoti list_cities, nors nė vienas klausimo žodis to tiesiogiai nenurodo.
Stebint atsakymo kūrimą
Laukti viso atsakymo tinka skriptui, tačiau bendraujant su naudotoju srautinis (streaming) režimas suteikia daug geresnę patirtį.
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}")
Įvykių srautas skirtas ne tik rodymui: tai taip pat geriausias derinimo įrankis, nes jis realiuoju laiku atskleidžia modelio pasirinktus įrankių kvietimus ir argumentus.
Kai įrankis nepavyksta
Dėka continue_on_fn_error=True, už aprėpties ribų esantis prašymas nieko nesugadina. Jei naudotojas paprašo oro sąlygų Tokijuje, get_weather grąžina savo klaidos JSON, modelis jį perskaito ir atsako pasiūlydamas faktiškai turimus miestus.
# 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..."
Galiausiai projektą sudaro keturi failai, iš kurių tik du turi logiką:
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=...
Svarbiausi punktai
- Pilnas MCP projektas = serveris (įrankiai) + klientas (agentas +
RunContext) - Serveris apibrėžia įrankius naudodamas
MCPServerir@app.tool()dekoratorius - Klientas sukuria agentą, atidaro
RunContextir pradeda pokalbius - Srautinis režimas leidžia laipsnišką rodymą
continue_on_fn_error=Trueelegantiškai tvarko įrankių klaidas- Visas kodas yra asinchroninis – kaip įvesties tašką naudok
asyncio.run()