Eżempju Sħiħ: Server Lokali b'Aġent
F'din il-paġna
Aġġornat fit-2 ta’ Novembru, 2026 — MCP Python SDK v2. Dan il-kors issa jsegwi l-verżjoni 2 tal-SDK
mcp(2.3.0 sal-2 ta’ Ottubru, 2026):MCPServertissostitwixxiFastMCP, il-konfigurazzjonijiet tat-trasport jiċċaqalqu lejnrun()jewstreamable_http_app(), u applikazzjoni esposta taħt isem ta’ host reali trid tiddikjara dak l-isem (transport_security). Din hija wkoll il-verżjoni meħtieġa mill-SDK ta’ Mistral: l-extramistralai[agents]jeħtieġmcp>=2.2.0,<3.0. Sorsi: X’inhu ġdid f’v2 · Gwida għall-Migrazzjoni · Iddispjega u skala. Addendum 3 ta’ Novembru: aqra r-riżultat ta’run_asyncminnresult.output_as_text(l-SDKmistralai3.7.0 m’għandux attributoutput), u fil-modalità ta’ streaming l-aħħar avveniment huwaRunResult, identifikat b’isinstance, bħall-eżempju uffiċjali tal-SDK.
L-assemblaġġ tal-biċċiet
Il-lezzjonijiet preċedenti ppreżentaw il-blokki tal-bini separatament: is-server u l-għodod tiegħu, il-klijent u l-RunContext tiegħu. Issa se tgħaqqadhom f’proġett li jaħdem—server MCP lokali li jipprovdi informazzjoni dwar it-temp, immexxi minn aġent Mistral kapaċi jwieġeb mistoqsijiet bil-lingwa naturali. Aqra l-kodiċi, iżda oqgħod attent ħafna għal dak li jiddeċiedi kull parti: is-server jiddeċiedi x’inhu possibbli, l-aġent jiddeċiedi x’inhu rilevanti.
Is-server: weather_server.py
Dan is-server jikkonsisti fi tliet għodod. L-ewwel wieħed jirritorna t-temp għal belt, it-tieni jqabbel żewġ bliet, u t-tielet jelenka x’fih id-database. Dan tal-aħħar mhuwiex dekorattiv: jagħti lill-mudell mod biex jiskopri l-ambitu disponibbli minflok ma jissuspetta ismijiet ta’ bliet.
# 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)
Żewġ dettalji tad-disinn jisħqu attenzjoni. L-għodod jinnormalizzaw l-input b’.lower().strip() għax il-mudell jista’ jikteb “Paris” jew “paris” skont kif ifformola l-utent. U meta belt tkun nieqsa, get_weather ma tħallix eċċezzjoni: tirritorna JSON ta’ żball li jelenka l-bliet magħrufa, u b’hekk tibdel il-falliment f’informazzjoni li l-mudell jista’ juża.
Il-klijent: main.py
Il-klijent jagħmel erba’ affarijiet f’ordni: jistabbilixxi Mistral, joħloq l-aġent, jiddeskrivi kif tniedi s-server, imbagħad jiftaħ il-RunContext biex iħaddem konversazzjonijiet f’katina.
# 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())
Innota l-mogħdija tas-server: Path(__file__).parent / "weather_server.py" tinsab il-fajl relattivament għall-iskritt minflok id-direttorju kurrenti. Din hija l-unika mod biex tiggarantixxi li t-tnedija taħdem irrispettivament minn fejn tniedi python main.py.
Tnedija tal-proġett
# Set API key
export MISTRAL_API_KEY="your_mistral_api_key"
# Launch client (it will launch the server automatically)
python main.py
Tniedi proċess wieħed biss. Il-klijent joħloq l-aġent Mistral, il-RunContext iniedi weather_server.py bħala proċess STDIO, jiskopri t-tliet għodod—get_weather, compare_weather, u list_cities—imbagħad, mistoqsija wara l-oħra, iħalli lill-mudell jagħżel liema minnhom isejjaħ qabel ma jintegra r-riżultati fir-risposta tiegħu. It-tielet mistoqsija fl-eżempju hija l-aktar interessanti biex tosservaha: biex tkun taf liema belt hija l-aktar sħuna, il-mudell m’għandux għażla ħlief li jgħaddi minn list_cities, anke jekk l-ebda kelma fil-mistoqsija ma tissuġġerixxi dan.
Kif tara r-risposta tinbena
Stenna għar-risposta sħiħa taħdem għal skritt; meta tkun quddiem utent, il-modalità streaming toffri esperjenza ferm aħjar.
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}")
Il-fluss tal-avvenimenti mhuwiex biss għad-display: huwa wkoll l-aqwa għodda ta’ debugġjar tiegħek, peress li jesponi s-sejħiet tal-għodod u l-argumenti magħżula mill-mudell f’ħin reali.
Meta għodda tfalli
Grazzi għal continue_on_fn_error=True, talba barra mill-ambitu ma tkissir xejn. Jekk l-utent jitlob it-temp f’Tokjo, get_weather tirritorna l-JSON ta’ żball tagħha, il-mudell jaqrah, u jirritorna billi jipproponi l-bliet attwalment disponibbli.
# 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..."
Fl-aħħar mill-aħħar, il-proġett jidħol f’erba’ fajls, li tnejn biss minnhom fihom loġika:
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=...
Punti Ewlenin
- Proġett MCP sħiħ = server (għodod) + klijent (aġent + RunContext)
- Is-server jiddefinixxi għodod b’dekoraturi
MCPServeru@app.tool() - Il-klijent joħloq l-aġent, jiftaħ il-RunContext, u jniedi konversazzjonijiet
- Il-modalità Streaming tippermetti display progressiv
continue_on_fn_error=Truetittratta l-iżbalji tal-għodod b’mod grazzjuż- Il-kodiċi kollu huwa asinkronu—uża
asyncio.run()bħala punt tad-dħul