Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Πλήρες παράδειγμα: Τοπικός διακομιστής με πράκτορα

Μάθημα 6 / 14 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Συναρμολόγηση των επιμέρους τμημάτων
  2. Ο διακομιστής: weather_server.py
  3. Ο πελάτης: main.py
  4. Εκτέλεση του έργου
  5. Παρακολούθηση της δόμησης της απάντησης
  6. Όταν ένα εργαλείο αποτυγχάνει
  7. Βασικά σημεία

Ενημερώθηκε στις 2 Νοεμβρίου 2026 — MCP Python SDK v2. Αυτό το μάθημα ακολουθεί πλέον την έκδοση 2 του mcp SDK (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 (το mistralai SDK 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() ως σημείο εισόδου