Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Näide tervikuna: kohalik server agendiga

Õppetund 6 / 14 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Osade kokkupanek
  2. Server: weather_server.py
  3. Klient: main.py
  4. Projekti käivitamine
  5. Vastuse kujunemise jälgimine
  6. Kui tööriist ebaõnnestub
  7. Peamised punktid

Uuendatud 2. novembril 2026 — MCP Python SDK v2. See kursus järgib nüüd mcp SDK versiooni 2 (seisuga 2. oktoober 2026 on see 2.3.0): MCPServer asendab FastMCP-i, transpordi seaded liiguvad meetoditesse run() või streamable_http_app() ning reaalse hostinime all avaldatav rakendus peab selle hostinime deklareerima (transport_security). See on ka versioon, mida nõuab Mistral SDK: lisa mistralai[agents] eeldab mcp>=2.2.0,<3.0. Allikad: Mis on uut v2-s · Migreerimisjuhend · Kasutuselevõtt ja skaleerimine. Lisand 3. novembril: loe run_async tulemust atribuudist result.output_as_text (Mistrali SDK 3.7.0-l puudub atribuut output) ja voogrežiimis on viimane sündmus RunResult, mis tuvastatakse isinstance-iga, nagu ametlikus SDK näites.

Osade kokkupanek

Eelmistes tundides käsitlesime ehitusplokke eraldi: serverit ja selle tööriistu, klienti ja selle RunContext-i. Nüüd paned need kokku toimivaks projektiks – kohalikuks MCP serveriks, mis pakub ilmateavet ja mida juhib Mistrali agent, oskades vastata küsimustele loomulikus keeles. Loe koodi läbi, kuid pööra erilist tähelepanu sellele, mida iga osa otsustab: server otsustab, mis on võimalik, agent otsustab, mis on asjakohane.

Server: weather_server.py

See server koosneb kolmest tööriistast. Esimene tagastab linna ilma, teine võrdleb kahte linna ja kolmas loetleb, mida andmebaas sisaldab. Viimane ei ole pelgalt ilu pärast: see annab mudelile võimaluse avastada olemasolevat ulatust, selle asemel et linnanimesid arvata.

# weather_server.py
"""Kohalik MCP server, mis pakub ilmatööriistu."""

from mcp.server.mcpserver import MCPServer
import json

app = MCPServer("Weather Service")

# Simuleeritud andmebaas
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:
    """Toob välja Prantsuse linna praeguse ilma.

    Args:
        city: Linna nimi väiketähtedega (paris, lyon, marseille jne)

    Returns:
        JSON temperatuuri, tingimuste ja niiskusega.
        Tagastab vea, kui linn on tundmatu.
    """
    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:
    """Võrdleb ilma kahe Prantsuse linna vahel.

    Args:
        city_a: Esimene linn (väiketähtedega)
        city_b: Teine linn (väiketähtedega)

    Returns:
        Mõlema linna temperatuuride ja tingimuste võrdlus
    """
    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:
    """Loetleb kõik ilmateabe andmebaasis olevad linnad.

    Returns:
        Linnade loend koos nende praeguse temperatuuriga
    """
    cities = [
        {"city": k.capitalize(), "temp": v["temp"], "condition": v["condition"]}
        for k, v in WEATHER_DATA.items()
    ]
    return json.dumps(cities, ensure_ascii=False)

Kaks disainidetaili väärivad tähelepanu. Tööriistad normaliseerivad sisendi .lower().strip() abil, sest mudel võib kasutaja sõnastusest sõltuvalt kirjutada kas „Paris“ või „paris“. Ja kui linn puudub, siis get_weather ei tekita erindit: see tagastab veateate JSON-vormingus, mis loetleb teadaolevad linnad, muutes ebaõnnestumise informatsiooniks, mida mudel saab kasutada.

Klient: main.py

Klient teeb järjest neli asja: initsialiseerib Mistrali, loob agendi, kirjeldab, kuidas serverit käivitada, ja avab seejärel RunContext-i vestluste aheldamiseks.

# main.py
"""MCP klient Mistrali agendiga ilmapäringute jaoks."""

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

# Konfiguratsioon
MISTRAL_API_KEY = os.environ.get("MISTRAL_API_KEY")
SERVER_PATH = Path(__file__).parent / "weather_server.py"

# Struktureeritud väljundvorming (valikuline)
class WeatherResponse(BaseModel):
    summary: str
    details: dict | None = None

async def main():
    # 1. Initsialiseeri Mistrali klient
    client = Mistral(api_key=MISTRAL_API_KEY)

    # 2. Loo 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. Konfigureeri kohalik MCP server
    server_params = StdioServerParameters(
        command="python",
        args=[str(SERVER_PATH)],
        env=None,
    )
    mcp_client = MCPClientSTDIO(stdio_params=server_params)

    # 4. Ava kontekst ja registreeri MCP klient
    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. Käivita vestlused
        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. Automaatne puhastus kontekstihaldurist väljumisel
    print("\nAgent and MCP server closed cleanly.")

if __name__ == "__main__":
    asyncio.run(main())

Pane tähele serveri teed: Path(__file__).parent / "weather_server.py" leiab faili skripti suhtes, mitte jooksvast kataloogist. See on ainus viis garanteerida, et käivitamine õnnestub sõltumata sellest, kust sa python main.py käivitad.

Projekti käivitamine

# Määra API võti
export MISTRAL_API_KEY="your_mistral_api_key"

# Käivita klient (see käivitab serveri automaatselt)
python main.py

Sa käivitad vaid ühe protsessi. Klient loob Mistrali agendi, RunContext käivitab weather_server.py STDIO protsessina, avastab kolm tööriista – get_weather, compare_weather ja list_cities – ning seejärel, küsimus küsimuse haaval, laseb mudelil valida, milliseid neist kutsuda, enne kui tulemused oma vastusesse integreerib. Näites olev kolmas küsimus on jälgimiseks kõige huvitavam: et teada saada, milline linn on kõige soojem, pole mudelil muud valikut kui kasutada list_cities, kuigi ükski sõna küsimuses sellele ei viita.

Vastuse kujunemise jälgimine

Täieliku vastuse ootamine sobib skripti jaoks; kasutajaga suheldes pakub voogrežiim (streaming) palju paremat kogemust.

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):
            # Viimane sündmus: täielik jooksu tulemus
            print(event.output_as_text)
        else:
            # Vahepealsed sündmused (tööriistakutsed jne)
            print(f"[Event] {event}")

Sündmuste voog ei ole mõeldud ainult kuvamiseks: see on ka sinu parim silumisvahend, kuna see paljastab mudeli valitud tööriistakutsed ja argumendid reaalajas.

Kui tööriist ebaõnnestub

Tänu continue_on_fn_error=True ei katkesta ulatusest väljas olev päring midagi. Kui kasutaja küsib Tokyo ilma, tagastab get_weather oma vea-JSON-i, mudel loeb seda ja reageerib, pakkudes tegelikult saadaolevaid linnu.

# Kui kasutaja küsib olematut linna:
# → get_weather tagastab {"error": "City tokyo not found..."}
# → Mudel loeb vea ja formuleerib vastuse ümber
# → "Vabandust, Tokyo pole minu andmebaasis. Siin on saadaolevad linnad..."

Kokkuvõttes mahub projekt nelja faili, millest ainult kaks sisaldavad loogikat:

weather-mcp-project/
├── weather_server.py    # MCP server (3 tööriista)
├── main.py              # Klient Mistrali agendiga
├── requirements.txt     # mcp>=2.2,<3, mistralai[agents], pydantic
└── .env                 # MISTRAL_API_KEY=...

Peamised punktid

  • Terviklik MCP projekt = server (tööriistad) + klient (agent + RunContext)
  • Server määratleb tööriistad MCPServer ja @app.tool() dekoratsioonidega
  • Klient loob agendi, avab RunContext-i ja käivitab vestlused
  • Voogrežiim (streaming) võimaldab järkjärgulist kuvamist
  • continue_on_fn_error=True käsitleb tööriistavigu sujuvalt
  • Kogu kood on asünkroonne – kasuta asyncio.run() sisendpunktina