Πλήρες παράδειγμα: Τοπικός διακομιστής με πράκτορα
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 2 Νοεμβρίου 2026 — MCP Python SDK v2. Αυτό το μάθημα ακολουθεί πλέον την έκδοση 2 του
mcpSDK (2.3.0 στις 2 Οκτωβρίου 2026): τοMCPServerαντικαθιστά τοFastMCP, οι ρυθμίσεις μεταφοράς μεταφέρονται στοrun()ή στοstreamable_http_app(), και μια εφαρμογή που εκτίθεται υπό πραγματικό όνομα host πρέπει να δηλώνει αυτό το όνομα host (transport_security). Αυτή είναι επίσης η έκδοση που απαιτείται από το Mistral SDK: το πρόσθετοmistralai[agents]απαιτείmcp>=2.2.0,<3.0. Πηγές: Τι νέο υπάρχει στο v2 · Οδηγός μετάβασης · Ανάπτυξη και κλιμάκωση. Προσθήκη 3 Νοεμβρίου: διαβάστε το αποτέλεσμα ενόςrun_asyncαπό τοresult.output_as_text(τοmistralaiSDK 3.7.0 δεν έχει το χαρακτηριστικόoutput), και σε λειτουργία ροής το τελευταίο συμβάν είναι έναRunResult, το οποίο αναγνωρίζεται μεisinstance, όπως στο επίσημο παράδειγμα του SDK.
Συναρμολόγηση των επιμέρους τμημάτων
Τα προηγούμενα μαθήματα παρουσίασαν τα δομικά στοιχεία ξεχωριστά: τον διακομιστή και τα εργαλεία του, τον πελάτη και το RunContext του. Τώρα θα τα συναρμολογήσετε σε ένα λειτουργικό έργο—έναν τοπικό διακομιστή MCP που παρέχει πληροφορίες καιρού, καθοδηγούμενο από έναν πράκτορα Mistral ικανό να απαντά σε ερωτήσεις σε φυσική γλώσσα. Διαβάστε τον κώδικα, αλλά δώστε ιδιαίτερη προσοχή στο τι αποφασίζει το κάθε μέρος: ο διακομιστής αποφασίζει τι είναι εφικτό, ο πράκτορας αποφασίζει τι είναι σχετικό.
Ο διακομιστής: weather_server.py
Αυτός ο διακομιστής αποτελείται από τρία εργαλεία. Το πρώτο επιστρέφει τον καιρό για μια πόλη, το δεύτερο συγκρίνει δύο πόλεις και το τρίτο απαριθμεί τι περιέχει η βάση δεδομένων. Το τελευταίο δεν είναι διακοσμητικό: δίνει στο μοντέλο έναν τρόπο να ανακαλύψει το διαθέσιμο εύρος αντί να μαντεύει ονόματα πόλεων.
# 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)
Δύο λεπτομέρειες σχεδιασμού αξίζουν προσοχής. Τα εργαλεία κανονικοποιούν την είσοδο με .lower().strip() επειδή το μοντέλο μπορεί να γράψει «Paris» ή «paris» ανάλογα με τη διατύπωση του χρήστη. Και όταν λείπει μια πόλη, το get_weather δεν προκαλεί εξαίρεση: επιστρέφει ένα JSON σφάλματος που απαριθμεί τις γνωστές πόλεις, μετατρέποντας την αποτυχία σε πληροφορία την οποία μπορεί να χρησιμοποιήσει το μοντέλο.
Ο πελάτης: main.py
Ο πελάτης κάνει τέσσερα πράγματα με σειρά: δημιουργεί στιγμιότυπο του Mistral, δημιουργεί τον πράκτορα, περιγράφει πώς να εκκινήσει τον διακομιστή και, τέλος, ανοίγει το RunContext για να αλυσιδωτούν οι συνομιλίες.
# 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())
Παρατηρήστε τη διαδρομή του διακομιστή: Path(__file__).parent / "weather_server.py" εντοπίζει το αρχείο σε σχέση με το σενάριο και όχι σε σχέση με τον τρέχοντα κατάλογο. Αυτός είναι ο μόνος τρόπος για να διασφαλίσετε ότι η εκκίνηση λειτουργεί ανεξάρτητα από το πού εκτελείτε την εντολή python main.py.
Εκτέλεση του έργου
# Set API key
export MISTRAL_API_KEY="your_mistral_api_key"
# Launch client (it will launch the server automatically)
python main.py
Ξεκινάτε μόνο μία διαδικασία. Ο πελάτης δημιουργεί τον πράκτορα Mistral, το RunContext εκκινεί το weather_server.py ως διαδικασία STDIO, ανακαλύπτει τα τρία εργαλεία—get_weather, compare_weather και list_cities—και στη συνέχεια, ερώτηση προς ερώτηση, επιτρέπει στο μοντέλο να επιλέξει ποια θα καλέσει πριν ενσωματώσει τα αποτελέσματα στην απάντησή του. Η τρίτη ερώτηση στο παράδειγμα είναι η πιο ενδιαφέρουσα για παρατήρηση: για να μάθει ποια πόλη είναι η θερμότερη, το μοντέλο δεν έχει άλλη επιλογή από το να περάσει μέσω του list_cities, παρόλο που καμία λέξη στην ερώτηση δεν το υπονοεί.
Παρακολούθηση της δόμησης της απάντησης
Η αναμονή για την πλήρη απάντηση λειτουργεί για ένα σενάριο· απέναντι σε έναν χρήστη, η λειτουργία ροής (streaming) προσφέρει πολύ καλύτερη εμπειρία.
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}")
Η ροή συμβάντων δεν χρησιμεύει μόνο για εμφάνιση: είναι επίσης το καλύτερο εργαλείο αποσφαλμάτωσης, καθώς εκθέτει σε πραγματικό χρόνο τις κλήσεις εργαλείων και τα ορίσματα που επιλέγει το μοντέλο.
Όταν ένα εργαλείο αποτυγχάνει
Χάρη στο continue_on_fn_error=True, ένα αίτημα εκτός εμβελέους δεν προκαλεί διακοπή. Αν ο χρήστης ζητήσει τον καιρό στο Τόκιο, το get_weather επιστρέφει το JSON σφάλματός του, το μοντέλο το διαβάζει και ανταποκρίνεται προτείνοντας τις πραγματικά διαθέσιμες πόλεις.
# 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..."
Στο τέλος, το έργο χωράει σε τέσσερα αρχεία, από τα οποία μόνο δύο περιέχουν λογική:
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=...
Βασικά σημεία
- Ένα πλήρες έργο MCP = διακομιστής (εργαλεία) + πελάτης (πράκτορας + RunContext)
- Ο διακομιστής ορίζει εργαλεία με τους διακοσμητές
MCPServerκαι@app.tool() - Ο πελάτης δημιουργεί τον πράκτορα, ανοίγει το RunContext και ξεκινά συνομιλίες
- Η λειτουργία ροής (streaming) επιτρέπει τη σταδιακή εμφάνιση
- Το
continue_on_fn_error=Trueδιαχειρίζεται κομψά τα σφάλματα των εργαλείων - Όλος ο κώδικας είναι ασύγχρονος—χρησιμοποιήστε το
asyncio.run()ως σημείο εισόδου